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
|
<?xml version="1.0" encoding="iso-8859-1"?>
<chapter xml:id="chapter-docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>About the DocBook Standard</title>
<sect1 xml:id="docbook-whatis">
<title>What is DocBook?</title>
<para>
First, don't be worried about learning another language or syntax
because DocBook is fairly straight forward and most contributors
simply cut-n-paste existing files, modify the content, then commit.
It's just plain text.
</para>
<para>
What is DocBook? The following is a quote from
<link xlink:href="&url.docbook;">DocBook: The Definitive Guide</link>:
</para>
<para>
<emphasis>
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.
</emphasis>
</para>
<para>
Simply this means that writing a DocBook file is no more than writing a text
file and using a few simple "tags" when needed. Like HTML, an opening tag is
a < bracket followed by the tag's name, optionally some arguments, and then
the > bracket (e.g. <para> for paragraphs). A closing tag is a <
bracket followed by a / sign, the tag name, then the closing > bracket
(e.g. </para> for paragraphs). For example uses, have a look at an existing
file within the PHP manual sources, or use the <link linkend="chapter-skeletons">
documentation skeletons</link>.
</para>
<para>
As described above, DocBook uses a similar structure to HTML with the main
difference being DocBook uses tags to define the <emphasis>meaning</emphasis>
whereas HTML often times defines the look and layout. So the idea behind
DocBook is to define as much as possible about the information so that build
and rendering software will intelligently output the text into many formats.
</para>
<para>
We use DocBook because it makes it easy to generate several formats of our
documents (HTML, PDF, Microsoft HTML Help (CHM), RTF, etc.), and DocBook is
the standard way for storing structured technical information.
</para>
<note>
<title>DocBook version upgrade history</title>
<para>
On January 2, 2007 we upgraded from DocBook 4.1.2 to 4.5 and then
to DocBook 5 at around June 20, 2007. These upgrades included changes
to most files in the phpdoc CVS repository.
</para>
</note>
</sect1>
<sect1 xml:id="docbook-refs">
<title>DocBook reference</title>
<para>
For information about the DocBook DTD, look here:
<link xlink:href="&url.docbook-dtd;">&url.docbook-dtd;</link>.
</para>
<para>
There is a DTD reference for DocBook at:
<link xlink:href="&url.docbook-dtdref;">&url.docbook-dtdref;</link>.
</para>
<para>
Get Going With DocBook, Notes for Hackers:
<link xlink:href="&url.docbook-intro;">&url.docbook-intro;</link>.
</para>
<para>
You can also find more information and downloads of style
sheets and other tools for DocBook in the DocBook Open
Repository at: <link xlink:href="&url.docbook.sf;">&url.docbook.sf;</link>.
</para>
<para>
You can also read the book <link xlink:href="&url.docbook;">DocBook:
The Definitive Guide</link> 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 <link xlink:href="&url.docbook.wiki;">DocBook Wiki</link>,
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
-->
|
