DocBook Guide for Authors of Geant4 User Manuals


Contents

  1. Introduction
  2. DocBook Tutorial by Example
    2.1 Simple Example Code
    2.2 Processing Simple Example Code
    2.3 Annotation to Simple Example Code
  3. Tag Mapping Table - (X)HTML vs. DocBook
    3.1 Important Note
    3.2 Mapping Table
    3.3 Special Characters
  4. References

1. Introduction

In the Lisbon Geant4 International Workshop (2006), we agreed to move all Geant4 users' manuals except 'Physics Reference Manual' from HTML to DocBook. This small note provides a basic guide to use DocBook when you update/revise a G4 manual.

DocBook is a markup language just like (X)HTML. This means you use tags to mark up the structure and semantics of a document. For example, a paragraph is marked up by a <para> and </para> pair in DocBook, where a <p> and </p> pair is used in (X)HTML. Although DocBook has a much richer tag set, there is a very good correspondence between (X)HTML and DocBook tags. Therefore it is straight forward for you to use DocBook, because you know well the (X)HTML tags. We provide in the later section a table of mapping between (X)HTML and DocBook tags. By referring this map, you can immediately start to update a Geant4 manual written in DocBook. However before making a jump-start it is better to have some general knowledge of DocBook. In the next section, we give you a gentle introduction of DocBook using a simple example code. We hope that this makes your jump-start a little bit smoother one.

You may wonder what is a merit to move to DocBook if there is such a good correspondence between (X)HTML and DocBook tags. The following are major merits of moving.


2. DocBook Tutorial by Example

Although we have said above that there is a very good correspondence between (X)HTML and DocBook tags, there are some number of key differences in the basic way to mark up a document in DocBook.

An easiest way to understand the basics of DocBook and its difference from (X)HTML is to read a simple DocBook document. In the following we provide a simple DocBook code and its annotation. We believe that, once you understand this simple example, you can make a jump-start to write the DocBook version of G4 users manual by referring the (X)HTML-DocBook mapping table in Section 3. If you want a more systematic tutorial, pick up one shown in References. For a detail explanation of all DocBook tags, see "O'Relly on-line book" shown in References.


2.1. Simple Example Code

The following example is created based on a very abbreviated version of 'Installation Guide' of Geant4 User Manual.


2.2. Processing Simple Example Code

The following is an HTML output generated from the above DocBook code:

There are several ways to get this HTML output from Simple Example Code.

1) xsltproc
This is an xml stylesheet processor written in C. It is available in most standard linux environments. Under the Windows environment it is available through 'cygwin'.

For example under the CERN lxplus environment, do as follows to get an HTML output from the above example DocBook code:

In the above 'xsltproc' command, '/usr/share/sgml/docbook/xsl-stylesheets-1.65.1-2/html/docbook.xsl' is a stylesheet used in converting docbook to html. The file 'example.xml' keeps 'SimpleExample Code'. The file 'output.html' is generated if there is no error in 'example.xml'. You can see 'output.html' with your favorite web browser.

When you want to run 'xsltproc' on your machine you have to take the following steps:

  1. Check if 'xsltproc' is available. If not then install it - most linux distributions have it in the distribution CD/DVD. If you want use a Windows machine, install it from a 'cygwin' mirror site.
  2. Check if the stylesheet named 'path-to-docbook-stylesheet/html/docbook.xsl' is available. If not then install the DocBook environment. Again most linux distributions have it. Also under a Windows machine 'cygwin' provides the DocBook environment.

2) xalan
This is a Java based stylesheet processor written. If you have a standard Java environment you probably can use this. Take note that you cannot use this under the CERN lxplus environment - when we tested we got an error of no enough space for object heap.

If you have an 'xalan' available environment, do as follows.

3) Firefox and Miscrosoft Internet Explore
Using so-called 'XML-stylesheet Processing Instruction', you can directly view a docbook document by the web browser if it awares the XSLT stylesheet - Firefox, MS-IE for examples.

For viewing you add the following lines colored red at the top of you docbook document:

Then you can directly view the xml file, for example:

[Memo]

The location of the two files ('docbook.xsl' and 'docbook.dtd') depends on your working environment. You may need to change the path to these files if you are not working under the 'cern/lxplus' environment.

4) XXE and Vex
You can process a docbook file using a so-called XML editor. XXE is an XML editor provided by the company 'XmlMind'. It is available in two versions - Standard Edition and Professional Edition. Standard Edition is free and still it has enough capability for our purpose.

Good points of this tool are

You can get this tool from the following site:

Another choice of an XML editor is 'Vex'. It is also free though it requires a Java environment. You can get this tool from the following site:

5) Which tool to use?
There are more tools available either freely or commercially, though ones mentioned above are good enough for our purpose.

You may ask which tool among above four we recommend to use. We guess that you may be attracted by WYSWYG tools like XXE or Vex, though we recommend to use 'xsltproc' or 'xalan' because they are used most commonly among the DocBook community.


2.3. Annotation to Simple Example Code

The following is annotation to the above simple DocBook code.


3. Tag Mapping Table - (X)HTML vs. DocBook

In this section, we show a table of mapping between (X)HTML and DocBook tags. It does not show a complete mapping, but covers all (X)HTML tags appeared in the most recent version of Geant4 User Manuals. By referring this map, we expect that you can immediately start to update a Geant4 manual in DocBook.

3.1 Important Note

Once you have changed a DocBook version of Geant4 document, it is mandatory that you verify your modifications using either one of tools described in Section 2.2. For this we recommend you to do the following unit test, ie. to process the file only you modified.

Suppose you have changed some part of the file 'introduction.xml' of 'User Manual - For Application Developers'. Then a possible way to validate your change is to execute the following command (under the CERN/lxplus environment):

If there is an error in your modification, then 'xsltproc' will tell you where it occurs. Correct the error and process it again. If there is no error anymore then you will get the output 'introduction.html'. Please never to commit your unverified DocBook file to CVS.

[Memo]


3.2 Mapping Table

The following table shows the mapping of (X)HTML tags that appeared in the Geant4 User Manuals to DocBook.

(X)HTML Tag - Alphabetical Order DocBook Tag 

 <a href="http://www.cern.ch">
   CERN
 </a>
 

 <ulink url="http://www.cern.ch">
   CERN
 </ulink>
 

 <a href="#Section1">
   Section1
 </a>
 

 <link linkend="Section1">
   Section1
 </link>

 or

 <xref linkend="Section1" />
 

 <b>emphasis</b>
 

 <emphasis>emphasis</emphasis>
 

 <blockquote>Quoted string</blockquote>
 

 <blockquote>
  <para>Quoted string</para>
 </blockquote>
 

 <body>body part</body>
 

 No corresponding tag
 

 <br />
 

 No corresponding tag 
 (Use <para> and </para>)
 

 <caption>title</caption>
 

 <title>title</title>
 

 <center>centering</center>
 

 No corresponding tag
 

 <code>
  program codes
 </code>
 

 <programlisting>
   program codes
 </programlisting>
 

 <dd>description</dd> 
 (See <dl>)
 

 <listitem>description</listitem>
 

 <dl>
   <dt>list name</dt>
   <dd>description</dd>
 </dl>
 

 <variablelist>
   <varlistentry>
     <term>list name</term>
     <listitem><para>description</para></listitem>
   </varlistentry>
 </variablelist>
 

 <dt>
   list name
 </dt>
 (See <dl>)
 

 <varlistentry>
   <term>list name</term>
 <varlistentry>
 

 <em>emphasis</em>
 

 <emphasis>emphasis</emphasis>
 

 <font ...>strings</font>
 

 No corresponding tag
 

 <head>header part</head>
 

 No corresponding tag
 

 <hr />
 

 No corresponding tag
 

 <html>
  ...
 </html>
 

 No corresponding tag
 

 <h1>head1</h1>
 <h2>head2</h2>
  .....
 <h5>head5</h5>
 

 <chapter>chapter</chapter>
 <sect1>section1</sect1>
 <sect2>section2</sect2>
  .....
 <sect5>section5</sect5>
 (See Section 2.3 for the usage 
  of these tags.)
 

 <i>emphasis</i>
 

 <emphasis>emphasis</emphasis>
 

 <img ... />
 

 <imageobject>
   <imagedata fileref="..." format="...">
 </imageobject>
 

 <kbd>commands</kbd>
 

 <literal>commands</literal>
 

 <li>list item</li>
 (See <ul>)
 

 <listitem>list item<listitem>
 

 <literal>strings</literal>
 

 <literal>strings</literal>
 

 <meta />
 

 No corresponding tag
 

 <ol>
   <li>list item</li>
 </ol>
 

 <orderedlist>
   <listitem><para>list item</para></listitem>
 </orderedlist>
 

 <p>paragraph</p>
 

 <para>paragraph</para>
 

 <pre>strings</pre>
 

 <literal>strings</literal>
 

 <span>region</span>
 

 No corrsponding tag
 

 <sub>subscript</sub>
 

 <subscript>subscript<subscript>
 

 <sup>superscript</sup>
 

 <superscript>superscript<superscript>
 

 <table>
   <tr>
     <th>header</th>
   </tr>
   <tr>
     <td>content</td>
   </tr>
 </table>
 

 <table>
   <tgroup>
   <row>
     <entry>
       <emphasis>header</emphasis>
     </entry>
   </row>
   <row>
     <entry>content</entry>
   </row>
   </tgroup>
 </table>
 

 <td>content</td>
 (See <table>)
 

 <entry>content</entry>
 

 <th>header</th>
 (See <table>)
 

 <entry><emphasis>
   header
 </emphasis><entry>
 (There is no one-to-one mapping in this case. 
  This shows only an example of mapping.)
 

 <title>title</title>
 

 <title>title</title>
 

 <tr></tr>
 (See <table>)
 

 <row></row>
 

 <tt>strings</tt>
 

 <literal>strings</literal>
 

 <u>strings</u>
 

 <emphasis>strings</emphasis>
 

 <ul>
   <li><para>list item</li>
 </ul>
 

 <itemizedlist>
   <listitem><para>list item</para></listitem>
 </itemizedlist>
 

 <!-- comments -->
 

 <!-- comments -->


3.3 Special Characters

As in (X)HTML the following reserved characters have to be escaped.

Reserved Character Escaped Format 

    <
    >
    &
 

    &lt;
    &gt;
    &amp;

For symbols and Greek letters, you should use the unicode directly

Not recommended to use Recommended to use (Unicode) 

    &alpha;
    &beta;
    .....
 

    &#x3b1;
    &#x3b2;
    .....

See the following page for unicodes of symbols and Greek letters.



4. References

General

Tutorials



Please send your comments about this document to Katsuya Amako.