1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
|
<?xml version="1.0" encoding="iso-8859-1"?>
<chapter id="chapter-docbook">
<title>About the DocBook Standard</title>
<sect1 id="docbook-whatis">
<title>What is DocBook?</title>
<para>
Quote from the introduction part of
<ulink url="&url.docbook;">DocBook: The Definitive Guide</ulink>:
</para>
<para>
DocBook is a very popular set of tags for describing books,
articles, and other prose documents, particularly technical
documentation. DocBook is defined using the native DTD
syntax of SGML and XML. Like HTML, DocBook is an example
of a markup language defined in SGML/XML.
</para>
<para>
Simply this means, that writing a DocBook file is no more,
than writing a text file, using some simple "tags" where
they are needed. An opening tag is a < bracket followed
by the tag's name, optinally some arguments, and a >
bracket (eg. <para> for paragraphs). A closing tag
is a < bracket followed by a / sign, the tag name and
a closing > bracket (eg. </para> for paragraphs).
The best way of studying what tags to use is to look into
the manual files, or the collected samples in the
<link linkend="chapter-skeletons">Documentation Skeletons</link>
section of this HOWTO. You can also download a full copy
of the DocBook book mentioned above, so you can search for
appropriate tags to use yourself.
</para>
<para>
We use DocBook because it is so easy to generate several
output formats of our documents (HTML, PDF, Microsoft
HTML Help, RTF, etc.), and is a world standard way of
storing structured technical information.
</para>
<para>
You don't need to know all tags of DocBook to contribute
to our work. If you are a translator, you need not translate
any tags or invent others, so you will only be interested
in the content between the opening and closing tags.
</para>
</sect1>
<sect1 id="docbook-and-html">
<title>DocBook for Native Speakers of HTML</title>
<para>
As you have seen above, DocBook is similar in file
structure to HTML. Although if you are used to HTML,
DocBook will probably seem pretty tag-verbose to you.
DocBook also uses logical tags, it has no (or at least
very few) layout-specific tags like HTML is full of.
The idea with DocBook is to tell as much as you can
about the information while writing it, so that software
can do more things with it. In DocBook you use tags
to mark the <emphasis>meaning</emphasis> of parts not
the presentation.
</para>
<para>
We use DocBook, because it eases the generation of the several
formats of the documentation, and acts as a central "meta format"
for all the things we would like to express in the documentation.
</para>
<para>
You cannot just invent tags in DocBook. There is a standard
set of tags you can use. If you are working on a translation,
please do not translate tags, as they need to stay as they
were written in the English files to work properly.
</para>
</sect1>
<sect1 id="docbook-refs">
<title>DocBook reference</title>
<para>
For information about the DocBook DTD, look here:
<ulink url="&url.docbook-dtd;">&url.docbook-dtd;</ulink>.
</para>
<para>
There is a DTD reference for DocBook at:
<ulink url="&url.docbook-dtdref;">&url.docbook-dtdref;</ulink>.
</para>
<para>
Get Going With DocBook, Notes for Hackers:
<ulink url="&url.docbook-intro;">&url.docbook-intro;</ulink>.
</para>
<para>
You can also find more information and downloads of style
sheets and other tools for DocBook in the DocBook Open
Repository at: <ulink url="&url.docbook.sf;">&url.docbook.sf;</ulink>.
</para>
<para>
You can also read the book <ulink url="&url.docbook;">DocBook:
The Definitive Guide</ulink> online, or buy it at a bookstore,
but be warned, that the first edition of the book (currently
the only printed edition available) contains outdated information.
</para>
<para>
There is a great <ulink url="&url.docbook.wiki;">DocBook Wiki</ulink>,
where you can collect information on DocBook editors, transformation
tools, etc.
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"howto.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
|
