Added a glossary with an alphabethical list of elements

along with a few other things.

diff --git a/doc/glossary.xml b/doc/glossary.xml
new file mode 100644 (file)
index 0000000..7598ed8
--- /dev/null
+++ b/doc/glossary.xml
@@ -0,0 +1,245 @@
+<?xml version="1.0"?>
+<!DOCTYPE chapter SYSTEM "../doc.dtd">
+<?xml-stylesheet type="text/css" href="xmldoc.css"?>
+
+<!--
+      XML documentation system
+      Original author :  Arjen Baart - arjen@andromeda.nl
+      Version         : $Revision: 1.1 $
+-->
+
+<chapter>
+<heading>Glossary</heading>
+
+ <para>
+ Alphabetical list of elements:
+ </para>
+ <description>
+  <item tag='abstract'>
+   Optional part of the <ref to='preamble'>title page</ref>. States in a few
+   sentences what the document is about.
+  </item>
+
+  <item tag='article'>
+   One of the <ref to='overall'>document styles</ref>.
+   Defines what kind of document this is.
+  </item>
+
+  <item tag='author'>
+   Part of the <ref to='preamble'>title page</ref>. States by whom the
+   document was written. There must be at least one author on a title page.
+  </item>
+
+  <item tag='book'>
+   One of the <ref to='overall'>document styles</ref>.
+   Defines what kind of document this is.
+  </item>
+
+  <item tag='chapter'>
+   The first level of <ref to='section'>sectioning</ref> elements.
+  </item>
+
+  <item tag='code'>
+   A form of <ref to='inline'>inline</ref> content for making <code>code</code>
+   examples. Usually renders to a monospace font.
+  </item>
+
+  <item tag='col'>
+   A single cell of content in a <ref to='table'>table</ref>.
+  </item>
+
+  <item tag='date'>
+   Part of the <ref to='preamble'>title page</ref>. States when the
+   document was written.
+  </item>
+
+  <item tag='description'>
+   Creates a <ref to='list'>list</ref> of descriptive items.
+  </item>
+
+  <item tag='doc'>
+   The single <ref to='overall'>root element</ref> of all XMLDoc documents.
+  </item>
+
+  <item tag='docinfo'>
+   Optional block of information about the document.
+   Contains a list of one or more <code>infoitem</code> elements.
+  </item>
+
+  <item tag='emph'>
+   A form of <ref to='inline'>inline</ref> content for making <emph>emphasized</emph>
+   text. Usually renders to some form of italic.
+  </item>
+
+  <item tag='enumerate'>
+   Creates a <ref to='list'>list</ref> of numbered items.
+  </item>
+
+  <item tag='footnote'>
+   Creates a numbered <ref to='footnote'>footnote</ref> at the bottom of the page.
+  </item>
+
+  <item tag='heading'>
+   Holds the heading of any one of the <ref to='section'>sectioning</ref> elements.
+   This heading is printed in larger font at the top of the sectioning
+   element and is used to create the table of contents (<code>toc</code>).
+  </item>
+
+  <item tag='include'>
+   Includes part of the document from another <ref to='include'>file</ref>.
+  </item>
+
+  <item tag='infoitem'>
+   An informational item on the <ref to='preamble'>title page</ref>. Holds
+   additional information about the document, such as version number or
+   organization.
+  </item>
+
+  <item tag='item'>
+   One item in a <ref to='list'>list</ref> of items.
+  </item>
+
+  <item tag='itemize'>
+   Creates a <ref to='list'>list</ref> of bulleted items.
+  </item>
+
+  <item tag='label'>
+   Used for <ref to='inref'>internal references</ref>.
+   Marks a point in the document that can be referred to by a <code>ref</code>
+   element.
+   The <code>name</code> attribute sets the name that can be referred.
+  </item>
+
+  <item tag='LaTeX'>
+   LaTeX <ref to='escape'>escape</ref> element. Copies the content of the
+   <code>command</code> attribute literally to the LaTeX output.
+  </item>
+
+  <item tag='newline'>
+   Forces a <ref to='break'>line break</ref> in the output document.
+  </item>
+
+  <item tag='newpage'>
+   Forces a <ref to='break'>page break</ref> in the output document.
+   Used only for LaTeX output.
+  </item>
+
+  <item tag='page'>
+   Used for <ref to='inref'>internal references</ref>.
+   Creates a page number to a <code>label</code> element.
+   The name of the <code>label</code> is put in the <code>to</code> attribute.
+   Used only for LaTeX output.
+  </item>
+
+  <item tag='para'>
+   The primary <ref to='block'>block-level</ref> element to hold the textual
+   content of the document.
+  </item>
+
+  <item tag='paragraph'>
+   The fifth level of <ref to='section'>sectioning</ref> elements.
+  </item>
+
+  <item tag='picture'>
+   Imports <ref to='graphics'>pictures</ref> into the document.
+  </item>
+
+  <item tag='quote'>
+   A quotation is a slightly indented <ref to='block'>block</ref> of text.
+  </item>
+
+  <item tag='ref'>
+   Used for <ref to='inref'>internal references</ref>.
+   Creates a reference to a <code>label</code> element.
+   The name of the <code>label</code> is put in the <code>to</code> attribute.
+  </item>
+
+  <item tag='reference'>
+   Used for <ref to='exref'>external references</ref>.
+   Creates a reference to an external document pointed to by the
+   <code>href</code> attribute.
+  </item>
+
+
+  <item tag='remark'>
+   A form of <ref to='inline'>inline</ref> content for making a <remark>remark</remark>
+   that stands out from the rest of the text. The final rendering is not really
+   defined and mey depend on other stylesheets.
+   E.g. for HTML output, this creates a <code>span</code> tag with <code>remark</code>
+   class attribute. The way this looks is determined by a CSS stylesheet.
+  </item>
+
+  <item tag='report'>
+   One of the <ref to='overall'>document styles</ref>.
+   Defines what kind of document this is.
+  </item>
+
+  <item tag='row'>
+   A row of columns in a <ref to='table'>table</ref>.
+  </item>
+
+  <item tag='section'>
+   The second level of <ref to='section'>sectioning</ref> elements.
+  </item>
+
+  <item tag='strong'>
+   A form of <ref to='inline'>inline</ref> content for making
+   <strong>strong</strong> text. Usually renderd in bold.
+  </item>
+
+  <item tag='sub'>
+   A form of <ref to='inline'>inline</ref> content for making
+   <sub>subscript</sub> text.
+  </item>
+
+  <item tag='subparagraph'>
+   The sixth level of <ref to='section'>sectioning</ref> elements.
+  </item>
+
+  <item tag='subsection'>
+   The third level of <ref to='section'>sectioning</ref> elements.
+  </item>
+
+  <item tag='subsubsection'>
+   The fourth level of <ref to='section'>sectioning</ref> elements.
+  </item>
+
+  <item tag='subtitle'>
+   Optionally, a document can have any number of subtitles added to
+   the <ref to='preamble'>title</ref>.
+  </item>
+
+  <item tag='sup'>
+   A form of <ref to='inline'>inline</ref> content for making
+   <sup>superscript</sup> text.
+  </item>
+
+  <item tag='table'>
+   Creates <ref to='table'>tabular</ref> content.
+  </item>
+
+  <item tag='thead'>
+   Optional first header row of a <ref to='table'>table</ref>.
+  </item>
+
+  <item tag='title'>
+   Mandatory first element of the <ref to='preamble'>title page</ref>.
+  </item>
+
+  <item tag='titlepage'>
+   Optional <ref to='preamble'>title page</ref> to hold the document's
+   title and author, along with some other information.
+  </item>
+
+  <item tag='toc'>
+   Automatically generated <ref to='preamble'>table of contents</ref>.
+  </item>
+
+  <item tag='verbatim'>
+   A <ref to='block'>block-level</ref> element to hold text with a
+   pre-determined layout. Mainly used for coding examples.
+  </item>
+
+ </description>
+
+</chapter>

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
 <!--
       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
 
       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>
    <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>
    <docinfo>

-      <infoitem label="Version">0.4</infoitem>
+      <infoitem label="Version">0.5</infoitem>

       <infoitem label="Organization">Andromeda Technology &amp; Automation</infoitem>
    </docinfo>
    <abstract>
       <infoitem label="Organization">Andromeda Technology &amp; Automation</infoitem>
    </docinfo>
    <abstract>


@@ -45,7 +45,7 @@
 <chapter>
 <heading>References</heading>
 <para>
 <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>
 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>
 </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"/>
 
 </para>
 </chapter>
 
 <include href="multifiles.xml"/>
 

+<include href="glossary.xml"/>
+

 <chapter>
 
 <heading>Things to do</heading>
 <itemize>
 <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>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>
 </itemize>
 </chapter>
 </report>

diff --git a/doc/inline.xml b/doc/inline.xml
index 80acf69..304846a 100644 (file)
--- a/doc/inline.xml
+++ b/doc/inline.xml
@@ -5,11 +5,11 @@
 <!--
       XML documentation system
       Original author :  Arjen Baart - arjen@andromeda.nl
 <!--
       XML documentation system
       Original author :  Arjen Baart - arjen@andromeda.nl

-      Version         : $Revision: 1.1 $
+      Version         : $Revision: 1.2 $

 -->
 
 <chapter>
 -->
 
 <chapter>

-<heading>Type styles and special characters</heading>
+<heading><label name='inline'/>Type styles and special characters</heading>

 <para>
 There are six type styles:
 <enumerate>
 <para>
 There are six type styles:
 <enumerate>


@@ -23,6 +23,42 @@ There are six type styles:
 </para>
 
 <section>
 </para>
 
 <section>

+<heading><label name='break'/>Line and page breaking</heading>
+
+<para>
+You can force the start of a new line of output with the empty
+<code>newline</code> element.
+This element has no attributes and no content.
+Starting a new page with the <code>newpage</code> element is only
+usefull when you create LaTeX output.
+</para>
+
+</section>
+
+<section>
+<heading><label name='escape'/>Output escapes</heading>
+
+<para>
+You can insert eny piece of text into a specific output target by using
+an escape element. An escape element is an element with the name of the
+output format and a single <code>command</code> attribute.
+For example, the <code>LaTeX</code> is used to put arbitrary text into
+the output of <code>xml2latex</code>.
+The content of its <code>command</code> attribute is copied literally
+into the output.
+One of the applications of the <code>LaTeX</code> escape element is to
+control the first line indent of a paragraph in LaTeX:
+
+<verbatim>
+&lt;LaTeX command='\setlength{\parindent}{0cm}'/&gt;
+</verbatim>
+
+Note that it is not possible to create HTML tags in this manner.
+</para>
+
+</section>
+
+<section>

 <heading>Special characters</heading>
 
 <para>
 <heading>Special characters</heading>
 
 <para>

diff --git a/doc/intro.xml b/doc/intro.xml
index 6e80a81..5dc1c92 100644 (file)
--- a/doc/intro.xml
+++ b/doc/intro.xml
@@ -5,7 +5,7 @@
 <!--
       XML documentation system
       Original author :  Arjen Baart - arjen@andromeda.nl
 <!--
       XML documentation system
       Original author :  Arjen Baart - arjen@andromeda.nl

-      Version         : $Revision: 1.1 $
+      Version         : $Revision: 1.2 $

 -->
 
 <chapter>
 -->
 
 <chapter>


@@ -14,7 +14,7 @@
 <para>
 <LaTeX command='\setlength{\parindent}{0cm}'/>
 <LaTeX command='\setlength{\parskip}{0.4cm}'/>
 <para>
 <LaTeX command='\setlength{\parindent}{0cm}'/>
 <LaTeX command='\setlength{\parskip}{0.4cm}'/>

-XML-doc is a collection of stylesheets and utilities, resembling a
+XMLDoc is a collection of stylesheets and utilities, resembling a

 documentation system like sgmltools and Linuxdoc.
 The objective is to prepare documentation in XML format.
 Other formats, like LaTeX, PostScript or HTML are then generated by
 documentation system like sgmltools and Linuxdoc.
 The objective is to prepare documentation in XML format.
 Other formats, like LaTeX, PostScript or HTML are then generated by


@@ -24,7 +24,7 @@ XSL stylesheets for a specific output format.
 </para>
 
 <section>
 </para>
 
 <section>

-<heading>XML-doc concepts</heading>
+<heading>XMLDoc concepts</heading>

 
 <para>
 Writing documents in XML is rather like writing them in HTML.
 
 <para>
 Writing documents in XML is rather like writing them in HTML.


@@ -42,4 +42,32 @@ There is a certain amount of structure you must adhere to.
 This structure is defined in the <emph>Document Type Definition (DTD)</emph>.
 </para>
 </section>
 This structure is defined in the <emph>Document Type Definition (DTD)</emph>.
 </para>
 </section>

+
+<section>
+<heading>XMLDoc in practice</heading>
+<para>
+Using XMLDoc is fairly simple.
+To use XMLDoc, all you need is a plain text editor, such as vim or emacs
+and a working installation of the XMLDoc utilities and stylesheets.
+The utilities constitute a special form of XSLT processor and a few
+shell scripts that invoke this XSLT processor with the proper style sheets.
+</para>
+
+<para>
+Since there are three XSLT sheets, there are also three shell scripts:
+<code>xml2html</code>, <code>xml2latex</code> and <code>xml2text</code>.
+These scripts transform the XMLDoc document into HTML, LaTeX and plain
+text output, respcetively.
+All you need to do is create your XML source document and use one of these
+scripts to transform the document an another format.
+For example, to transform this guide into a LaTeX document, you could
+use:
+
+<verbatim>
+   xml2latex guide.xml >guide.tex
+</verbatim>
+
+Note that the transformed document is written to standard output.
+</para>
+</section>

 </chapter>
 </chapter>

diff --git a/doc/main.css b/doc/main.css
index 4ada333..dbb3494 100644 (file)
--- a/doc/main.css
+++ b/doc/main.css
@@ -46,7 +46,7 @@ div.titlepage
 
 p
 {
 
 p
 {

-   font-size : 90%;
+   font-size : 100%;

 }
 
 span.remark
 }
 
 span.remark


@@ -64,3 +64,9 @@ table
    border-collapse : collapse;
    padding : 1px ;
 }
    border-collapse : collapse;
    padding : 1px ;
 }

+
+dt
+{
+   font-weight : bold ;
+   top-margin  : 1ex;
+}

diff --git a/doc/makefile b/doc/makefile
index 9c1daa2..bdebd00 100644 (file)
--- a/doc/makefile
+++ b/doc/makefile
@@ -7,7 +7,7 @@
 .obj.eps:
        tgif -print -eps -color $<
 
 .obj.eps:
        tgif -print -eps -color $<
 

-XMLS = guide.xml intro.xml overall.xml block.xml inline.xml multifiles.xml
+XMLS = guide.xml intro.xml overall.xml block.xml inline.xml multifiles.xml glossary.xml

 IMAGES=
 
 PICTURES=
 IMAGES=
 
 PICTURES=

diff --git a/doc/multifiles.xml b/doc/multifiles.xml
index 6a44031..ea9c715 100644 (file)
--- a/doc/multifiles.xml
+++ b/doc/multifiles.xml
@@ -5,7 +5,7 @@
 <!--
       XML documentation system
       Original author :  Arjen Baart - arjen@andromeda.nl
 <!--
       XML documentation system
       Original author :  Arjen Baart - arjen@andromeda.nl

-      Version         : $Revision: 1.1 $
+      Version         : $Revision: 1.2 $

 -->
 
 <chapter>
 -->
 
 <chapter>


@@ -16,7 +16,7 @@ and output.
 <emph>Well, not really. Multiple output files is not implemented yet :-)</emph>
 </para>
 <section>
 <emph>Well, not really. Multiple output files is not implemented yet :-)</emph>
 </para>
 <section>

-<heading>Multiple input files</heading>
+<heading><label name='include'/>Multiple input files</heading>

 <para>
 You do not need to create one single big XML file that contains
 all of your story.
 <para>
 You do not need to create one single big XML file that contains
 all of your story.

diff --git a/doc/overall.xml b/doc/overall.xml
index d662a76..22ac06c 100644 (file)
--- a/doc/overall.xml
+++ b/doc/overall.xml
@@ -5,12 +5,12 @@
 <!--
       XML documentation system
       Original author :  Arjen Baart - arjen@andromeda.nl
 <!--
       XML documentation system
       Original author :  Arjen Baart - arjen@andromeda.nl

-      Version         : $Revision: 1.1 $
+      Version         : $Revision: 1.2 $

 -->
 
 
 <chapter>
 -->
 
 
 <chapter>

-<heading>Overall document structure</heading>
+<heading><label name='overall'/>Overall document structure</heading>

 
 <para>
 All XML-doc documents are set up in a similar way.
 
 <para>
 All XML-doc documents are set up in a similar way.


@@ -60,7 +60,7 @@ The example shows a minimal XML-doc document:
 </verbatim>
 
 <section>
 </verbatim>
 
 <section>

-<heading>Preamble</heading>
+<heading><label name='preamble'/>Preamble</heading>

 <para>
 The document preamble is everything that comes before the real page of text.
 Typical elements of the preamble are the title page and the table of contents.
 <para>
 The document preamble is everything that comes before the real page of text.
 Typical elements of the preamble are the title page and the table of contents.


@@ -104,12 +104,15 @@ All it takes is an empty <strong>toc</strong> element:
 <para>
 The table of contents is optional, but if you use it, it must come
 between the title page and the first chapter.
 <para>
 The table of contents is optional, but if you use it, it must come
 between the title page and the first chapter.

+<remark>Note for LaTeX: to actually make the table of contents, you
+need to run <strong>latex</strong> twice. LaTeX does not do this in
+a single pass.</remark>

 </para>
 
 </section>
 
 <section>
 </para>
 
 </section>
 
 <section>

-<heading>Sectioning and Paragraphs</heading>
+<heading><label name='section'/>Sectioning and Paragraphs</heading>

 
 <para>
 After the opening tag of the first chapter, the document really begins.
 
 <para>
 After the opening tag of the first chapter, the document really begins.


@@ -131,6 +134,12 @@ Note that the names are equivalent to their counterparts in LaTeX.
 </para>
 
 <para>
 </para>
 
 <para>

+Just as in LaTeX, the <code>article</code> document type does not have
+a <code>chapter</code> element.
+The top-level sectioning element for an <code>article</code> is a
+<code>section</code>.
+</para>
+<para>

 After the open tag of a sectioning element (<code>chapter</code>,
 <code>section</code>, <code>subsection</code> or <code>subsubsection</code>, etc.)
 comes the <strong>heading</strong> element, followed by the block level content
 After the open tag of a sectioning element (<code>chapter</code>,
 <code>section</code>, <code>subsection</code> or <code>subsubsection</code>, etc.)
 comes the <strong>heading</strong> element, followed by the block level content