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.3 $
   9 -->
  10
  11
  12 <chapter>
  13 <heading><label name='overall'/>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><label name='preamble'/>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 <remark>Note for LaTeX: to actually make the table of contents, you
 108 need to run <strong>latex</strong> twice. LaTeX does not do this in
 109 a single pass.</remark>
 110 </para>
 111
 112 </section>
 113
 114 <section>
 115 <heading><label name='section'/>Sectioning and Paragraphs</heading>
 116
 117 <para>
 118 After the opening tag of the first chapter, the document really begins.
 119 The structure of the document is layed out by its chapters, sections
 120 within the chapters, subsections within the sections and so on.
 121 Just as in LaTeX and HTML, there are six levels of sectioning elements available:
 122 </para>
 123 <enumerate>
 124 <item><code>chapter</code>: For top-level chapters.</item>
 125 <item><code>section</code>: For second-level sections, i.e. 1.1, 1.2, 1.3
 126       and so on.</item>
 127 <item><code>subsection</code>: For third-level sections, i.e. 1.1.1, 1.1.2
 128       and so on.</item>
 129 <item><code>subsubsection</code>: For fourth-level sections
 130       (you get the idea).</item>
 131 <item><code>paragraph</code>: The fifth-level sections</item>
 132 <item><code>subparagraph</code>: The sixth and final level.</item>
 133 </enumerate>
 134 <para>
 135 Note that the names are equivalent to their counterparts in LaTeX.
 136 </para>
 137
 138 <para>
 139 Just as in LaTeX, the <code>article</code> document type does not have
 140 a <code>chapter</code> element.
 141 The top-level sectioning element for an <code>article</code> is a
 142 <code>section</code>.
 143 </para>
 144 <para>
 145 After the open tag of a sectioning element (<code>chapter</code>,
 146 <code>section</code>, <code>subsection</code> or <code>subsubsection</code>, etc.)
 147 comes the <strong>heading</strong> element, followed by the block level content
 148 as discussed in <ref to='block'>chapter </ref><page to='block'> on page </page>.
 149 </para>
 150
 151 </section>
 152
 153 <section>
 154 <heading>Linking with style sheets</heading>
 155 <para>
 156 You can use a 'normal' CSS stylesheet with the HTML output from
 157 <strong>xml2html</strong>, by using the <strong>style</strong> attribute
 158 in the <strong>doc</strong> element.
 159 Here is an example:
 160 </para>
 161 <verbatim>
 162
 163 &lt;doc style="main.css"&gt;
 164
 165 </verbatim>
 166 </section>
 167 </chapter>
 168