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
   6 <!--
   7       XML documentation system
   8       Original author :  Arjen Baart - arjen@andromeda.nl
   9       Version         : $Revision: 1.2 $
  10
  11       This document is prepared for XMLDoc. Transform to HTML,
  12       LaTeX, Postscript or plain text with XMLDoc utilities and
  13       XSLT sheets from http://www.andromeda.nl/projects/xmldoc/
  14 -->
  15
  16 <report>
  17 <titlepage>
  18    <title>XML documentation system</title>
  19    <subtitle>Document preparation and conversion in XML</subtitle>
  20
  21    <author>Arjen Baart <code>&lt;arjen@andromeda.nl&gt;</code></author>
  22    <date>Aug 18, 2003</date>
  23    <docinfo>
  24       <infoitem label="Version">0.5</infoitem>
  25       <infoitem label="Organization">Andromeda Technology &amp; Automation</infoitem>
  26    </docinfo>
  27    <abstract>
  28    This guide explains the concepts of <strong>XMLDoc</strong> and discusses
  29    the features available to prepare documentation.
  30    <strong>XMLDoc</strong> uses XSLT transformations to turn the XML source
  31    document into a number of other formats.
  32    </abstract>
  33 </titlepage>
  34
  35 <toc/>
  36
  37 <include href="intro.xml"/>
  38
  39 <include href="overall.xml"/>
  40
  41 <include href="block.xml"/>
  42
  43 <include href="inline.xml"/>
  44
  45 <chapter>
  46 <heading>References</heading>
  47 <para>
  48 <label name='exref'/>Creating hypertext references is as simple as it is in HTML.
  49 The element used for references is <strong>reference</strong>, which
  50 adheres to the <emph>XLink</emph> syntax.
  51 We need to add one more attribute to the usual <strong>href</strong>
  52 attribute.
  53 For example:
  54 <verbatim>
  55 &lt;reference xml:link="simple"
  56     href="http://www.andromeda.nl/project/xmldoc/xmldoc.html"&gt;
  57 The XMLDoc website
  58 &lt;/reference&gt;
  59 provide the installation instructions.
  60 </verbatim>
  61 <reference xml:link="simple"
  62     href="http://www.andromeda.nl/projects/xmldoc/xmldoc.html">
  63 The XMLDoc website
  64 </reference>
  65 provides the installation instructions.
  66 </para>
  67
  68 <para>
  69 <label name='inref'/>An internal reference requires at least two elements.
  70 The reference itself, which points to another place in the document and a label
  71 to which the reference refers.
  72 There can of course be multiple references to a single label.
  73 The point in the document where reference can point to is marked
  74 by a <code>label</code> element.
  75 A <code>label</code> is an empty element with exactly one attribute,
  76 the <code>name</code> of the label.
  77 Each <code>label</code> must have a <code>name</code> that is unique
  78 throughout the document.
  79 Here is an example of a label:
  80
  81 <verbatim>
  82    &lt;label name='example'/&gt;
  83 </verbatim>
  84
  85 You can refer to a label from any other place in the document by using a
  86 <code>ref</code> or a <code>page</code> element.
  87 The <code>page</code> element creates a reference to the page number on which
  88 the <code>label</code> is printed.
  89 This is of course only usefull on printed media, such as LaTeX.
  90 The <code>ref</code> and <code>page</code> elements also require one
  91 attribute:
  92
  93 <verbatim>
  94    &lt;ref to='example'&gt;example reference&lt;/ref&gt;
  95 </verbatim>
  96 The required attribute <code>to</code> holds the name of the
  97 label to which the reference refers.
  98 The <code>ref</code> element is usually not empty.
  99 The <ref to='inline'>inline</ref><page to='inline'>, described on page </page>
 100 content of the <code>ref</code> element is used to create the reference.
 101 For example, when the document is transformed into HTML, the content
 102 will become a clickable link.
 103 The content of the <code>page</code> element is only renedered in LaTeX output.
 104 </para>
 105 </chapter>
 106
 107 <include href="multifiles.xml"/>
 108
 109 <include href="glossary.xml"/>
 110
 111 <chapter>
 112
 113 <heading>Things to do</heading>
 114 <itemize>
 115 <item>Math</item>
 116 <item>XML Schema definition and validation</item>
 117 <item>Font sizes</item>
 118 <item>Center environment</item>
 119 <item>A utility to create XMLDoc tables from raw ASCII data</item>
 120 <item>Index generation</item>
 121 <item>Bibliographics</item>
 122 <item>Man pages</item>
 123 <item>List of figures, list of tables</item>
 124 </itemize>
 125 </chapter>
 126 </report>
 127 </doc>