How to write documents for Practical XML

publishxml

This is a documentation generator for a core subset of DocBook, with some useful extensions. It currently generates html and pdf output. It has a clean, extensible design, and is much faster than some other open source Docbook tools.

generatedtd

This generates a dtd from a collection of xml documents expressing a single schema.

validatexml

This validates an xml document against a dtd.

processtopics

processjournal, processtasks and processrecords are topic-based applications illustrating the transformation of a user-defined xml vocabulary to DocBook. A topic tree is defined using a simple xml vocabulary. This can be processed by processtopics to generate topic tree documentation. Other documents can structure their contents implicitly by reference to this tree.

processjournal

This processes a topic-based journal written in a simple vocabulary with embedded DocBook.

processrecords

This processes a topic-based structured document written in a simple vocabulary with embedded DocBook. PDF output is generated recursively for all levels in the topic hierarchy, making it easy to view any sub-tree of the document

processtasks

This processes a topic-based project task description, generating project management documentation.

tutorial1

This shows how easy it is to build and process an in-memory tree representation of an xml file. Try it with your own application-specific vocabulary.

Sections

<section id="sectionId">
  <title>Section Title</title>
  <!-- section content comes here -->
</section>

Note the xml comment tags. The section id attribute is optional. You can use it on any tag to provide a target for an internal link. Id attributes must be unique in a document. See Links below.

You can nest sections. There are tags to support nesting (sect1, sect2, sect3, etc), but they offer no advantage over plain section.

There are two special classes of the <section> element which have to be used as the outermost element when defining a new XML file.

1. class="topic": This section class defines a new html page. It also creates a section in the pdf version. Therefore, please complete it with a <title> element.
2. class="import": This section class defines a mere import of the enclosed xml without the creation of a new html page. This is especially useful when the XML material shall be used in various locations of the website. No explicit section is created in the pdf version. A title element is therefore not required.

Paragraphs

<para>Paragraph 1 content.</para>
<para>Paragraph 2 content.</para>

Paragraph 1 content.

Paragraph 2 content.

Lists

Itemized (bullet) list:

<itemizedlist>
  <listitem>First item content.</listitem>
  <listitem>Second item content.</listitem>
</itemizedlist>

• First item content.
• Second item content.

Ordered (numbered) list:

<orderedlist>
  <listitem>First item content.</listitem>
  <listitem>Second item content.</listitem>
</orderedlist>

1. First item content.
2. Second item content.

Lists can be nested.

Tables

Table with title:

<table frame="sides">
  <title>Table Title</title>
  <tgroup cols="2">
    <colspec colwidth="30mm"/>
    <colspec colwidth="30mm"/>
    <thead>
      <row>
        <entry>column1 title</entry>
        <entry>column2 title</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>row1 column1 content</entry>
        <entry>row1 column2 content</entry>
      </row>
      <row>
        <entry>row2 column1 content</entry>
        <entry>row2 column2 content</entry>
      </row>
    </tbody>
  </tgroup>
</table>

Complex table with multicolumn and multirow spans:

<informaltable frame="all">
  <tgroup cols="4">
    <colspec colnum="1" colname="c1" colwidth="30mm"/>
    <colspec colnum="2" colname="c2" colwidth="30mm"/>
    <colspec colnum="3" colname="c3" colwidth="30mm"/>
    <colspec colnum="4" colname="c4" colwidth="30mm"/>
    <thead>
      <row>
        <entry morerows="1">header multirow1</entry>
        <entry morerows="1">header multirow2</entry>
        <entry namest="c3" nameend="c4">header multicolumn</entry>
      </row>
      <row>
         <entry colname="c3">subcolumn1</entry>
         <entry colname="c4">subcolumn2</entry>
      </row>
    </thead>
    <tbody>
      <row>
         <entry morerows="2">body multirows</entry>
         <entry>body column2</entry>
         <entry morerows="1">body multirows</entry>
         <entry>body column4</entry>
      </row>
      <row>
         <entry>body column2</entry>
         <entry>body column4</entry>
      </row>
      <row>
         <entry namest="c2" nameend="c4">body multicolumn</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>

For a table without a title, use informaltable which is otherwise the same. Specify column widths in mm. For more information on tables in DocBook please consult DocBook XSL: The Complete Guide.

Table with rows with alternating colours but without lines:

<table alternating="yes" rules="none">
  <title>Alternating Table</title>
  <tgroup cols="2">
    <colspec colwidth="60mm"/>
    <colspec colwidth="60mm"/>
    <thead>
      <row>
        <entry>column1 title</entry>
        <entry>column2 title</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>row1 column1 content</entry>
        <entry>row1 column2 content</entry>
      </row>
      <row>
        <entry>row2 column1 content</entry>
        <entry>row2 column2 content</entry>
      </row>
      <row>
        <entry>row3 column1 content</entry>
        <entry>row3 column2 content</entry>
      </row>
      <row>
        <entry>row4 column1 content</entry>
        <entry>row4 column2 content</entry>
      </row>
      <row>
        <entry>row5 column1 content</entry>
        <entry>row5 column2 content</entry>
      </row>
      <row>
        <entry>row6 column1 content</entry>
        <entry>row6 column2 content</entry>
      </row>
    </tbody>
  </tgroup>
</table>

For a table without internal lines set the rules attribute to "none". If not set, the attribute defaults to "all" which draws all internal lines. Do not use rules="none" together with multicolumns or multirows! To build a table with alternating row colours set the attribute alternating to "yes". Leaving out this attribute or setting it to any other value will produce a table without row colours.

Graphics

<graphic fileref="../graphics/itm_viewlog1.png" width="70%"/>

Image size is controlled by specifying the width relative to the page width in percent.

Links are always relative to the file location!

Links

Link to document on the Web:

For the full DocBook tagset, see 
<ulink url="http://www.docbook.org/tdg/en/html/docbook.html">
DocBook: The Definitive Guide</ulink>.

Link to an email address:

Author:
<ulink url="mailto:john.storrs@ukaea.org.uk">John Storrs</ulink>.

Link to another document on the local server:

Here is the <ulink url="../imports/style.css">style sheet</ulink> for this document.

Links are always relative to the file location!

<section id="target1">
<para id="target2">
<anchor id="target3"/>

This links to the <link linkend="sectionId">Sections</link> section above.

Verbatim

<screen>
This is verbatim layout
   It is typeset in a fixed-width font.
      Spacing is preserved.
</screen>

This is verbatim layout
   It is typeset in a fixed-width font.
      Spacing is preserved.

Text Formatting

The text formatting elements typewriter text and emphasis are included in DocBook.

<mono>This is typewriter text.</mono>

<emphasis>This is emphasized text.</emphasis>

File Inclusion

Simple xml file inclusion is achieved like this:

<include file="introduction.xml"/>
<include file="developmenttools.xml"/>
<include file="hardware.xml"/>
<include file="firmware.xml"/>
<include file="software.xml"/>
<include file="hardwaretesting.xml"/>
<include file="softwareupdates.xml"/>

The included xml file must have a <section> element with a class attribute as its root element. There are two special classes of the <section> element.

1. class="topic": This section class defines a new html page. It also creates a section in the pdf version. Therefore, please complete it with a <title> element.
2. class="import": This section class defines a mere import of the enclosed xml without the creation of a new html page. This is especially useful when the XML material shall be used in various locations of the website. No explicit section is created in the pdf version. A title element is therefore not required.

Important:
Do NOT create circular inclusions!

Maths

Latex maths can be embedded in DocBook documents in a math element. Here are some examples:

<math>\[ 2\sum_{i=1}^n a_i \int^b_a f_i(x)g_i(x)\,\mathrm{d}x \]</math>

<math>$$ 2\sum_{i=1}^n a_i \int^b_a f_i(x)g_i(x)\,\mathrm{d}x $$</math>

To get a better alignment for inline maths, use the <inmath> element.

<inmath>\[ 2\sum_{i=1}^n a_i \int^b_a f_i(x)g_i(x)\,\mathrm{d}x \]</inmath>

Text Formatting

The standard set of text formatting elements, like bold face, italic, and underline have been added to the DocBook scope.

<bold>This is bold face.</bold>

<italic>This is italic.</italic>

<underline>This is underlined text.</underline>

Text Colors

A total of 10 text colors have been added to the DocBook definitions. The <color> tag carries the attribute name which allows specification of the text color by name (see table below).

Boxes

<box>
This environment frames the included text with a box. It is a mandatory
alternative to <screen> if a <math> element is included.
</box>

Lines

<hrule/>

Special Characters

Special characters like diacritics have been added to the DocBook scope. If you like to use diacritics in xml, please use the html entities, i.e. &eacute; for é.
For a complete list of diacritics please see HTML:Special Characters. Only the diacritics have been included so far.

Blanks

no spaces<newline/>
<spaces/>1 space<newline/>
<spaces number="1"/>1 space<newline/>
<spaces number="2"/>2 spaces<newline/>
<spaces number="3"/>3 spaces<newline/>
<spaces number="4"/>4 spaces<newline/>
<spaces number="5"/>5 spaces<newline/>
<spaces number="10"/>10 spaces<newline/>