doc/guide.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE doc SYSTEM "../doc.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../html.xsl"?>
   4 <doc style="main.css"
   5      xmlns:xi="http://www.w3.org/2001/XInclude">
   6
   7 <!--
   8       XML documentation system
   9       Original author :  Arjen Baart - arjen@andromeda.nl
  10       Version         : $Revision: 1.3 $
  11
  12       This document is prepared for XMLDoc. Transform to HTML,
  13       LaTeX, Postscript or plain text with XMLDoc utilities and
  14       XSLT sheets from http://www.andromeda.nl/projects/xmldoc/
  15 -->
  16
  17 <report>
  18 <titlepage>
  19    <title>XML documentation system</title>
  20    <subtitle>Document preparation and conversion in XML</subtitle>
  21
  22    <author>Arjen Baart <code>&lt;arjen@andromeda.nl&gt;</code></author>
  23    <date>Oct 17, 2007</date>
  24    <docinfo>
  25       <infoitem label="Version">0.8</infoitem>
  26       <infoitem label="Organization">Andromeda Technology &amp; Automation</infoitem>
  27    </docinfo>
  28    <abstract>
  29    This guide explains the concepts of <strong>XMLDoc</strong> and discusses
  30    the features available to prepare documentation.
  31    <strong>XMLDoc</strong> uses XSLT transformations to turn the XML source
  32    document into a number of other formats.
  33    </abstract>
  34 </titlepage>
  35
  36 <toc/>
  37
  38 <xi:include href="intro.xml"/>
  39
  40 <xi:include href="overall.xml"/>
  41
  42 <xi:include href="block.xml"/>
  43
  44 <xi:include href="inline.xml"/>
  45
  46 <chapter>
  47 <heading>References</heading>
  48 <para>
  49 <label name='exref'/>Creating hypertext references is as simple as it is in HTML.
  50 The element used for references is <strong>reference</strong>, which
  51 adheres to the <emph>XLink</emph> syntax.
  52 We need to add one more attribute to the usual <strong>href</strong>
  53 attribute.
  54 For example:
  55 </para>
  56
  57 <verbatim>
  58 &lt;reference xml:link="simple"
  59     href="http://www.andromeda.nl/project/xmldoc/xmldoc.html"&gt;
  60 The XMLDoc website
  61 &lt;/reference&gt;
  62 provide the installation instructions.
  63 </verbatim>
  64
  65 <para>
  66 <reference xml:link="simple"
  67     href="http://www.andromeda.nl/projects/xmldoc/xmldoc.html">
  68 The XMLDoc website
  69 </reference>
  70 provides the installation instructions.
  71 </para>
  72
  73 <para>
  74 <label name='inref'/>An internal reference requires at least two elements.
  75 The reference itself, which points to another place in the document and a label
  76 to which the reference refers.
  77 There can of course be multiple references to a single label.
  78 The point in the document where reference can point to is marked
  79 by a <code>label</code> element.
  80 A <code>label</code> is an empty element with exactly one attribute,
  81 the <code>name</code> of the label.
  82 Each <code>label</code> must have a <code>name</code> that is unique
  83 throughout the document.
  84 Here is an example of a label:
  85 </para>
  86
  87 <verbatim>
  88    &lt;label name='example'/&gt;
  89 </verbatim>
  90
  91 <para>
  92 You can refer to a label from any other place in the document by using a
  93 <code>ref</code> or a <code>page</code> element.
  94 The <code>page</code> element creates a reference to the page number on which
  95 the <code>label</code> is printed.
  96 This is of course only usefull on printed media, such as LaTeX.
  97 The <code>ref</code> and <code>page</code> elements also require one
  98 attribute:
  99 </para>
 100
 101 <verbatim>
 102    &lt;ref to='example'&gt;example reference&lt;/ref&gt;
 103 </verbatim>
 104
 105 <para>
 106 The required attribute <code>to</code> holds the name of the
 107 label to which the reference refers.
 108 The <code>ref</code> element is usually not empty.
 109 The <ref to='inline'>inline</ref><page to='inline'>, described on page </page>
 110 content of the <code>ref</code> element is used to create the reference.
 111 For example, when the document is transformed into HTML, the content
 112 will become a clickable link.
 113 The content of the <code>page</code> element is only renedered in LaTeX output.
 114 </para>
 115 </chapter>
 116
 117 <xi:include href="multifiles.xml"/>
 118
 119 <xi:include href="glossary.xml"/>
 120
 121 <chapter>
 122
 123 <heading>Other XML applications</heading>
 124 <section>
 125 <heading>MathML</heading>
 126 <math xmlns:math="http://www.w3.org/1998/Math/MathML">
 127   <math:mrow>
 128     <math:msup>
 129       <math:mfenced open="[" close="]">
 130         <math:mrow>
 131           <math:mi>&theta;</math:mi>
 132           <math:mo>+</math:mo>
 133
 134           <math:mi>b</math:mi>
 135         </math:mrow>
 136       </math:mfenced>
 137       <math:mn>260</math:mn>
 138     </math:msup>
 139     <math:mo>+</math:mo>
 140     <math:msub>
 141
 142       <math:mfenced open="{" close="}">
 143         <math:mrow>
 144           <math:mi>a</math:mi>
 145           <math:mo>+</math:mo>
 146           <math:mi>b</math:mi>
 147         </math:mrow>
 148       </math:mfenced>
 149
 150       <math:mi>i</math:mi>
 151     </math:msub>
 152   </math:mrow>
 153 </math>
 154 </section>
 155 </chapter>
 156
 157 <chapter>
 158
 159 <heading>Things to do</heading>
 160 <itemize>
 161 <item>MathML and SVG conversion to LaTeX</item>
 162 <item>XML Schema definition and validation</item>
 163 <item>Font sizes</item>
 164 <item>Center environment</item>
 165 <item>A utility to create XMLDoc tables from raw ASCII data</item>
 166 <item>Index generation</item>
 167 <item>Bibliographics</item>
 168 <item>Man pages</item>
 169 <item>List of figures, list of tables</item>
 170 </itemize>
 171 </chapter>
 172 </report>
 173 </doc>