d662a76350679555b985b1ddbdf9dc7b40282df8
[xmldoc.git] / doc / overall.xml
1 <?xml version="1.0"?>
2 <!DOCTYPE chapter SYSTEM "../doc.dtd">
3 <?xml-stylesheet type="text/xsl" href="../html.xsl"?>
4
5 <!--
6       XML documentation system
7       Original author :  Arjen Baart - arjen@andromeda.nl
8       Version         : $Revision: 1.1 $
9 -->
10
11
12 <chapter>
13 <heading>Overall document structure</heading>
14
15 <para>
16 All XML-doc documents are set up in a similar way.
17 Just as every other XML file, a doument starts with the XML and DOCTYPE
18 declarations:
19 </para>
20
21 <verbatim>
22
23 &lt;?xml version="1.0"?&gt;
24 &lt;!DOCTYPE doc SYSTEM "doc.dtd"&gt;
25
26 </verbatim>
27
28 <para>
29 These declarations are followed by the <strong>doc</strong> element.
30 The <strong>doc</strong> element contains the entire document.
31 The next element within the <strong>doc</strong> element defines the
32 type of document.
33 This can be a <strong>book</strong>, <strong>article</strong> or a
34 <strong>report</strong>.
35 Structurally, there is no real difference between either type of
36 document but in LaTeX, they result in different layout styles.
37 Each type of document contains any number
38 of <strong>chapter</strong> elements.
39 The example shows a minimal XML-doc document:
40 </para>
41
42 <verbatim>
43
44 &lt;?xml version="1.0"?&gt;
45 &lt;!DOCTYPE doc SYSTEM "doc.dtd"&gt;
46
47 &lt;doc&gt;
48
49    &lt;book&gt;
50
51       &lt;chapter&gt;
52          &lt;heading&gt;The only chapter&lt;/heading&gt;
53
54       &lt;/chapter&gt;
55
56    &lt;/book&gt;
57
58 &lt;/doc&gt;
59
60 </verbatim>
61
62 <section>
63 <heading>Preamble</heading>
64 <para>
65 The document preamble is everything that comes before the real page of text.
66 Typical elements of the preamble are the title page and the table of contents.
67 You can create a title page with the <strong>titlepage</strong> tag.
68 As the name suggests, the title page holds at least the title of the document.
69 Other elements in the title page are the author(s),
70 the date and the abstract.
71 Here is an example of a title page:
72 </para>
73
74 <verbatim>
75 &lt;titlepage&gt;
76    &lt;title&gt;XML documentation system&lt;/title&gt;
77    &lt;author&gt;Arjen Baart  &lt;arjen@andromeda.nl&gt;&lt;/author&gt;
78    &lt;date&gt;April 8, 2002&lt;/date&gt;
79    &lt;abstract&gt;
80    This guide explains the concepts of &lt;strong&gt;XMLDoc&lt;/strong&gt; and discusses
81    the features available to prepare documentation.
82    &lt;strong&gt;XMLDoc&lt;/strong&gt; uses XSLT transformations to turn the XML source
83    document into a number of other formats.
84    &lt;/abstract&gt;
85 &lt;/titlepage&gt;
86 </verbatim>
87
88 <para>
89 The <strong>titlepage</strong> must have a <strong>title</strong> and
90 at least one <strong>author</strong> element.
91 The <strong>date</strong> and <strong>abstract</strong> elements are
92 optional, but if you use them, you must put them in this order.
93 </para>
94
95 <para>
96 The table of contents is particularly easy to create.
97 All it takes is an empty <strong>toc</strong> element:
98 </para>
99
100 <verbatim>
101    &lt;toc/&gt;
102 </verbatim>
103
104 <para>
105 The table of contents is optional, but if you use it, it must come
106 between the title page and the first chapter.
107 </para>
108
109 </section>
110
111 <section>
112 <heading>Sectioning and Paragraphs</heading>
113
114 <para>
115 After the opening tag of the first chapter, the document really begins.
116 The structure of the document is layed out by its chapters, sections
117 within the chapters, subsections within the sections and so on.
118 Just as in LaTeX and HTML, there are six levels of sectioning elements available:
119 <enumerate>
120 <item><code>chapter</code>: For top-level chapters.</item>
121 <item><code>section</code>: For second-level sections, i.e. 1.1, 1.2, 1.3
122       and so on.</item>
123 <item><code>subsection</code>: For third-level sections, i.e. 1.1.1, 1.1.2
124       and so on.</item>
125 <item><code>subsubsection</code>: For fourth-level sections
126       (you get the idea).</item>
127 <item><code>paragraph</code>: The fifth-level sections</item>
128 <item><code>subparagraph</code>: The sixth and final level.</item>
129 </enumerate>
130 Note that the names are equivalent to their counterparts in LaTeX.
131 </para>
132
133 <para>
134 After the open tag of a sectioning element (<code>chapter</code>,
135 <code>section</code>, <code>subsection</code> or <code>subsubsection</code>, etc.)
136 comes the <strong>heading</strong> element, followed by the block level content
137 as discussed in <ref to='block'>chapter </ref><page to='block'> on page </page>.
138 </para>
139
140 </section>
141
142 <section>
143 <heading>Linking with style sheets</heading>
144 <para>
145 You can use a 'normal' CSS stylesheet with the HTML output from
146 <strong>xml2html</strong>, by using the <strong>style</strong> attribute
147 in the <strong>doc</strong> element.
148 Here is an example:
149 <verbatim>
150
151 &lt;doc style="main.css"&gt;
152
153 </verbatim>
154 </para>
155 </section>
156 </chapter>
157