along with a few other things.
--- /dev/null
+<?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>
<!--
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
<subtitle>Document preparation and conversion in XML</subtitle>
<author>Arjen Baart <code><arjen@andromeda.nl></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 & Automation</infoitem>
</docinfo>
<abstract>
<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>
</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>
+ <label name='example'/>
+</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>
+ <ref to='example'>example reference</ref>
+</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>
<!--
XML documentation system
Original author : Arjen Baart - arjen@andromeda.nl
- Version : $Revision: 1.1 $
+ Version : $Revision: 1.2 $
-->
<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>
</enumerate>
</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>
+<LaTeX command='\setlength{\parindent}{0cm}'/>
+</verbatim>
+
+Note that it is not possible to create HTML tags in this manner.
+</para>
+
+</section>
+
<section>
<heading>Special characters</heading>
<!--
XML documentation system
Original author : Arjen Baart - arjen@andromeda.nl
- Version : $Revision: 1.1 $
+ Version : $Revision: 1.2 $
-->
<chapter>
<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
</para>
<section>
-<heading>XML-doc concepts</heading>
+<heading>XMLDoc concepts</heading>
<para>
Writing documents in XML is rather like writing them in HTML.
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>
p
{
- font-size : 90%;
+ font-size : 100%;
}
span.remark
border-collapse : collapse;
padding : 1px ;
}
+
+dt
+{
+ font-weight : bold ;
+ top-margin : 1ex;
+}
.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=
<!--
XML documentation system
Original author : Arjen Baart - arjen@andromeda.nl
- Version : $Revision: 1.1 $
+ Version : $Revision: 1.2 $
-->
<chapter>
<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.
<!--
XML documentation system
Original author : Arjen Baart - arjen@andromeda.nl
- Version : $Revision: 1.1 $
+ Version : $Revision: 1.2 $
-->
<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.
</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 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>
-<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.
Note that the names are equivalent to their counterparts in LaTeX.
</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.)
projects / xmldoc.git / commitdiff