Added a glossary with an alphabethical list of elements

[xmldoc.git] / doc / guide.xml

diff --git a/doc/guide.xml b/doc/guide.xml
index 8a5659b..f314395 100644 (file)
--- a/doc/guide.xml
+++ b/doc/guide.xml
@@ -6,7 +6,7 @@
 <!--
       XML documentation system
       Original author :  Arjen Baart - arjen@andromeda.nl
-      Version         : $Revision: 1.1 $
+      Version         : $Revision: 1.2 $
 
       This document is prepared for XMLDoc. Transform to HTML,
       LaTeX, Postscript or plain text with XMLDoc utilities and
@@ -19,9 +19,9 @@
    <subtitle>Document preparation and conversion in XML</subtitle>
 
    <author>Arjen Baart <code>&lt;arjen@andromeda.nl&gt;</code></author>
-   <date>Aug 28, 2002</date>
+   <date>Aug 18, 2003</date>
    <docinfo>
-      <infoitem label="Version">0.4</infoitem>
+      <infoitem label="Version">0.5</infoitem>
       <infoitem label="Organization">Andromeda Technology &amp; Automation</infoitem>
    </docinfo>
    <abstract>
@@ -45,7 +45,7 @@
 <chapter>
 <heading>References</heading>
 <para>
-Creating hypertext references is as simple as it is in HTML.
+<label name='exref'/>Creating hypertext references is as simple as it is in HTML.
 The element used for references is <strong>reference</strong>, which
 adheres to the <emph>XLink</emph> syntax.
 We need to add one more attribute to the usual <strong>href</strong>
@@ -66,23 +66,61 @@ provides the installation instructions.
 </para>
 
 <para>
-Internal references with label, ref and page (page=LaTeX only).
+<label name='inref'/>An internal reference requires at least two elements.
+The reference itself, which points to another place in the document and a label
+to which the reference refers.
+There can of course be multiple references to a single label.
+The point in the document where reference can point to is marked
+by a <code>label</code> element.
+A <code>label</code> is an empty element with exactly one attribute,
+the <code>name</code> of the label.
+Each <code>label</code> must have a <code>name</code> that is unique
+throughout the document.
+Here is an example of a label:
+
+<verbatim>
+   &lt;label name='example'/&gt;
+</verbatim>
+
+You can refer to a label from any other place in the document by using a
+<code>ref</code> or a <code>page</code> element.
+The <code>page</code> element creates a reference to the page number on which
+the <code>label</code> is printed.
+This is of course only usefull on printed media, such as LaTeX.
+The <code>ref</code> and <code>page</code> elements also require one
+attribute:
+
+<verbatim>
+   &lt;ref to='example'&gt;example reference&lt;/ref&gt;
+</verbatim>
+The required attribute <code>to</code> holds the name of the
+label to which the reference refers.
+The <code>ref</code> element is usually not empty.
+The <ref to='inline'>inline</ref><page to='inline'>, described on page </page>
+content of the <code>ref</code> element is used to create the reference.
+For example, when the document is transformed into HTML, the content
+will become a clickable link.
+The content of the <code>page</code> element is only renedered in LaTeX output.
 </para>
 </chapter>
 
 <include href="multifiles.xml"/>
 
+<include href="glossary.xml"/>
+
 <chapter>
 
 <heading>Things to do</heading>
 <itemize>
-<item>Internal cross-referencing</item>
-<item>Newline and newpage</item>
+<item>Math</item>
+<item>XML Schema definition and validation</item>
+<item>Font sizes</item>
 <item>Center environment</item>
 <item>A utility to create XMLDoc tables from raw ASCII data</item>
 <item>Index generation</item>
 <item>Bibliographics</item>
 <item>Man pages</item>
+<item>List of figures, list of tables</item>
 </itemize>
 </chapter>
 </report>