Using DocBook

Introduction

The OGSA-DAI documentation is written using the DocBook format. This aims to serve as a crib sheet for DocBook (subject to wiki formatting allowing an appropriate rendering of what is procued by processing DocBook). These notes attempts to demonstrates how DocBook tags are used and what their effect is (useful for testing how they render to other formats).

This is a DocBook cook book - it is not intended to be a complete DocBook reference. For a more complete description of how DocBook may be used see the references at the end. If there is anything that is NOT clear in this documentation ask and if you think that you can make it clearer then change the document accordingly.

This used to be an appendix in the OGSA-DAI documentation but post release 3.0 it got taken out of the bundled documentation.

Use of Entities

It is useful to use entities as variables for information that will change from one documentation version to the next. For instance we can use &ODVerNum; to provide the current version of the OGSA-DAI distribution - in this instance this is set to 3.1. Entities are stored in a file called globalentities. Use of this potentially could allow for certain pieces of information to be rapidly changed from one version of the documentation to the next. However,care must be taken when using this - if you say anything that pertains to a specific version of the documentation then it should NOT use such a variable.

Document Processing

Currently documentation is processed using xsltpro (web site). This is invoked through a Makefile with a number of targets: all, developer, user and product. These are different views of the documentation. The all view is supposed to incorporate content from all the other files. There is also also a clean target that removes all the output files produced. Output of the content goes into the Output directory in a directory corresponding to one of the above targets with an html subdirectory where the rendered content can be found. Later, we hope to have pdf, xhtml, etc. views of the documentation.

Structure

Typically each of the chapter files has the following structure:

<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
[
   
<!-- Global entities file -->
<!ENTITY % myents SYSTEM "../globalentities">
%myents;

]>

<!-- Need a unique id for a chapter -->
<chapter id="UniqueChapterID">
  <title>Title for my Chapter</title>

<!-- Index entries are optional but it could be useful for navigation. 
     Secondary index is optional. -->

<!-- Each section needs to have a unique id -->
<section id="UniqueSecId">
  <title>Section Title</title>

<!-- nested sections become subsections and so on. -->
<section id="SubSecId">
   <title>This is a sub section</title>

<para>
Some content at last ...
</para>

</section>

</section>

</chapter>

Using Xinclude

Xinclude allows the document to be broken up into smaller chunks using files that are included into the main document. To do this use:

<xi:include   
    xmlns:xi="http://www.w3.org/2001/XInclude"  
    href="FileToBeIncluded.xml" /> 

Currently the granularity of the decomposition is now done at various levels.

Problem with this set-up is that if, for some reason, your document fails to process then it will not be included in the final documentation. Unless you pay attention to the error messages and warnings this will happen silently. For that reason you can put a xi:fallback that will complain if this happens:

<xi:include   
    xmlns:xi="http://www.w3.org/2001/XInclude"  
    href="FileToBeIncluded.xml">
  <xi:fallback>
    <warning>
      <para>
        Failure to include FileToBeIncluded.xml. Please fix!
      </para>
    </warning>  
  </xi:fallback>
</xi:include>        

This way you will have some warning that something has gone wrong.

More information on xinclude is available here.

Listings

To list a piece of code use:

<para>
<programlisting>
 Code would go here
</programlisting>
</para>   

Which is rendered as:

  Code would go here

Note that any ‘<’ would have to be turned into the appropriate entitity, &lt; in this case. Alternatively you could put your code in a CDATA section:

<programlisting><![CDATA[  
    Code goes here
]]>   
</programlisting>

This then does not need any special characters to be escaped.

Typographical Stuff

Some hints about changing the typography of text:

• For italicized text use <emphasis>...<emphasis>.
• For bold text use <emphasis role="strong"> ...<emphasis>.
• For type script use <computeroutput>...<computeroutput> or <filename>...<filename>. For large blocks of text use <screen>...</screen>.

Lists

Unordered Lists

To use bullet lists:

<itemizedlist>
 <listitem>
   <para>
    item 1
   </para>
 </listitem>
 <listitem>
  <para>
    item 1
  </para>
 </listitem>      
</itemizedlist>

Which renders as:

• item 1
• item 1

Ordered Lists

To use bullet lists:

<orderedlist>
  <listitem>
    <para>
      item 1
    </para>
  </listitem>
  <listitem>
    <para>
      item 2
    </para>
  </listitem>      
</orderedlist>

Which renders as:

1. item 1
2. item 2

You can specify the type of numbering by adding a numeration attribute with one of the following:

• arabic giving 1, 2, 3, ...
• loweralpha giving a, b, c, ...
• lowerroman giving i, ii, iii, ...
• upperalpha giving A, B, C, ...
• upperroman giving I, II, III, ...

Definition List

A definition list

<variablelist>
   <varlistentry>
   <term>Definition term goes here</term>
   <listitem><para>And definition/description goes here</para></listitem>
   </varlistentry>
   <varlistentry>
      <term>Another term goes here</term>
      <listitem><para>And more stuff goes here</para></listitem>
   </varlistentry>
</variablelist>   

which is rendered as:

Definition term goes here

And definition/description goes here

Another term goes here

And more stuff goes here

More Information on Lists

More information on lists is available here.

Adding Images

To add an image use:

<figure id="ODLogo">
<title>This is the title for the OGSA-DAI Logo.</title>
<mediaobject>
<imageobject role="html">
   <imagedata fileref="images/ogsadai-medium.gif" align="center" />
</imageobject>
<textobject>
   <phrase>This goes in the image ALT tag.</phrase>
</textobject>
<caption>
   Hector is the OGSA-DAI logo caption.
</caption>
</mediaobject>
</figure>

which produces:

The image would be centred but don't know how to do this using the wiki formatting rules.

This goes in the image ALT tag. would be in the image ALT tag.

There would also be an image caption of the sort:

Figure O.1. This is title for the OGSA-DAI Logo.

The O refers to the section number.

Note: currently you should place any images in the images directory. Any images there get copied to the corresponding location by the Makefile. You need to prepend your image image file with images/.

For images use the titles to produce captions and not the caption element.

Note: caption (title element) rendering is not centred. This worked ok with the xsl stylesheets version 1.69 but the image did not (it did not display because an issue with using xinclude). Currently this is being done using a css rule (p.title in default.css).

You can resize images by using the scale attribute:

   <imagedata fileref="images/ogsadai-medium.gif" align="center" scale="80"/>

to scale to 80% of the original size. For more information and other options see here.

Image Guidelines

Image Package to Use

The recommended image package to use for images is DIA.

Diagram Layout

Some guidelines about layout:

• Ensure layout is consistent, e.g. service components on the right clients on the left, etc.
• Consistent colouring of components.
• Keeping the diagram sources.

More information on Images

More information on images is available here.

Adding Tables

Informal Tables

To add an informal table you can use the following pattern:

<informaltable align="center">
  <tgroup cols="3">
   <thead>
     <row>
      <entry>header1</entry>
      <entry>header2</entry>
      <entry>header3</entry>
     </row>
   </thead>
   <tbody>
     <row>
       <entry>a1</entry>
       <entry>b1</entry>
       <entry>c1</entry>
     </row>
     <row>
       <entry>a2</entry>
       <entry>b2</entry>
       <entry>c2</entry>
      </row>
      <row>
       <entry>a3</entry>
       <entry>b3</entry>
       <entry>c3</entry>
      </row>                                    
   </tbody>
   </tgroup>
</informaltable>   

Which roughly renders as:

header1	header2	header3
a1	b1	c1
a2	b2	c2
a3	b3	c3

Note: Centering of tables being done in default.css by the div.table-contents table and div.informaltable table rules.

Formal Tables

You can add formal tables which also provide captions or titles (not both) in a document as well which can appear in a list of tables (note for the table example below you can only use a title and not a caption).

<table frame='all' id="SampleTable"><title>Sample Table.</title>
<tgroup cols='5' align='left' colsep='1' rowsep='1'>
<colspec colname='c1'/>
<colspec colname='c2'/>
<colspec colname='c3'/>
<colspec colnum='5' colname='c5'/>
<thead>
<row>
  <entry namest="c1" nameend="c2" align="center">Horizontal Span</entry>
  <entry>a3</entry>
  <entry>a4</entry>
  <entry>a5</entry>
</row>
</thead>
<tfoot>
<row>
  <entry>f1</entry>
  <entry>f2</entry>
  <entry>f3</entry>
  <entry>f4</entry>
  <entry>f5</entry>
</row>
</tfoot>
<tbody>
<row>
  <entry>b1</entry>
  <entry>b2</entry>
  <entry>b3</entry>
  <entry>b4</entry>
  <entry morerows='1' valign='middle'><para>  <!-- Pernicous Mixed Content -->
  Vertical Span</para></entry>
</row>
<row>
  <entry>c1</entry>
  <entry namest="c2" nameend="c3" align='center' morerows='1' valign='bottom'>Span Both</entry>
  <entry>c4</entry>
</row>
<row>
  <entry>d1</entry>
  <entry>d4</entry>
  <entry>d5</entry>
</row>
</tbody>
</tgroup>
<caption>Here is a caption</caption>
</table>    

which renders as:

Horizontal Span		a3	a4	a5
f1	f2	f3	f4	f5
b1	b2	b3	b4	Vertical Span
c1	Span Both		c4
d1			d4	d5

Table O.1. Sample Table.

More Info on Tables

More information on using tables in DocBook available here. Syntax for table and for informaltable.

Adding Links

Adding a URL

To add links use:

<ulink url="http://www.ogsadai.org.uk">http://www.ogsadai.org.uk</ulink>   

which then provides a link:

http://www.ogsadai.org.uk

These can be in-lined in the main text.

Linking Internally

There are a number of different ways that you can cross link across document elements:

• Using xref: allows one to link to existing elements. One points to the corresponding id of the element you wish to link to:

            <xref linkend="DBLinks"/>
  

  Links to the beginning of the appropriate section labelled by DBLinks, note that replaces the section title. More complex behaviour is also possible, see here.
• Using link: with the link tag you can specify your ownlink text:

           <link linkend="DBLinks">linking section</link> 
  

  More info on syntax here.

Appears as linking section which points to the same location as the xref above.

More information on Linking

More information on links at here.

Adding Index Entries

One can add an index entry by placing the following mark-up in your content:

<indexterm>
<primary>IndexEntry</primary>
<secondary>Subentry</secondary>
</indexterm>

The secondary entry is optional. One can add tertiary and other elements and see also elements. The index entry picks up the location it has to point to from the context of where it is placed - a good location might be after the section title. The result of this process can be viewed in the index of the resulting document.

Adding Glossary Entries

Glossary entries are stored in Misc/Glossary.xml. To add an entry use:

<glossentry id="IdForTerm">
 <glossterm>
  DefinedTerm
 </glossterm>
 <glossdef>
   <para>
    Term definition
   </para>
  </glossdef>
</glossentry>

This can then be referenced from the main body of the text by using:

<glossterm linkend="IdForTerm">DefinedTerm</glossterm>	

DocBook Admonitions

DocBook allows admonitions to be created to give warnings, tips, cautions, ..., etc. The colours used are determined in the default.css stylesheet. They have been put in as images below.

<important>
<para>
Do not deliver results via SOAP.
</para>
</important>

Which renders to:

while:

<warning>
<para>
Do not deliver results via SOAP.
</para>
</warning>   

Gives:

and

<note>
<para>
Do not deliver results via SOAP.
</para>
</note>   

gives:

and

<tip>
<para>
Do not deliver results via SOAP.
</para>
</tip>   

gives:

with:

<caution>
<para>
Do not deliver results via SOAP.
</para>
</caution>   

giving:

Customizing the Rendering Output

Most of the options of how the DocBook is rendered into html are configured in the custom.xsl file.

Note: Some of the rendering of the html is produced by the css so if some of the stuff you are producing does not quite look right it is worth checking the files in DocBook/css/*.css.

Conditional Rendering

One may often want to create conditional content with a document so that a section is only shown under certain conditions. In DocBook this is referred to as profiling. The attributes in the table below (this table has been borrowed from the DocBook? XSL: The Complete Guide book by Bob Stayton) can decorate almost all DocBook defined elements. These can then be used for conditional compilation to obtain particular views of the documentation.

Attribute Name	Description
arch	Computer or chip architecture, such as i386.
condition	General purpose conditional attribute, with no preassigned semantics.
conformance	Standards conformance, such as lsb (Linux Standards Base).
lang	Language code, such as de_DE.
os	Operating system.
revision	Editorial revision, such as v2.1.
revisionflag	Revision status of the element, such as changed. This attribute has a fixed set of values to choose from.
role	General purpose attribute, with no preassigned semantics. Use with caution for profiling.
security	Security level, such as high.
userlevel	Level of user experience, such as beginner.
vendor	Product vendor, such as apache.

or the purposes of this documentation we shall use the condition attribute to distinguish threads of the documentation that pertain to the release that works with Globus by assigning it the value daigt40 and the Axis version by assigning this attribute the value daiaxis1.

For example to specify that a list item or paragraph is for specific versions of OGSA-DAI you can do things like:

<para condition="daigt40">
For OGSA-DAI GT we do...
</para>

<para condition="daiaxis1">
For OGSA-DAI Axis we do...
</para>

<itemizedlist>
  <listitem condition="daigt40">
For OGSA-DAI GT we do...
  </listitem>
  <listitem condition="daiaxis1">
For OGSA-DAI Axis we do...
  </listitem>
</itemizedlist>

<phrase condition="daigt40">
  <para>
The phrase element is useful for grouping multiple elements
relating to OGSA-DAI GT...
  </para>
  <para>
Like this...
  </para>
</phrase>

<phrase condition="daiaxis1">
  <para>
And likewise for OGSA-DAI Axis...
  </para>
  <para>
Like this...
  </para>
</phrase>

There is also a daiall condition for content that should only be included when a complete document set is being produced not a set for specific platforms or versions of OGSA-DAI.

Profiling is not enabled by default - a different stylesheet has to be used to achieve that: html/profile-chunk.xsl for an html rendering. All elements will still be output unless the desired profiled sections are specified:

--stringparam  profile.condition "daigt40"

in which case only those condition attributes which have a value of daigt40 will be included. If the xref or link elements are used in the documentation then a two-phase process is required (which is a lot more complicate to describe so look at the Makefile to see how it is done. More information on profiling is available here.

Tooling

You can use your favourite editor to compose DocBook but there are some other wysiwyg type tooling for DocBook, e.g.:

• XMLMind Personal Edition is free for non-commercial use and has some restrictions in functionality.

A number of other tools are described here. However, one of the issues with using such tooling is that it can screw up the format laid out by files that have been hand edited which can be a major pain to people that edit the XML files directly (like me).

References

The following sources may provide further information about DocBook that may prove to be useful.

• Docbook: The Definitive Guide is an O'Reilly book which is available on-line. This appears to be the standard reference for DocBook. In particular, there is an index of all the DocBook elements which can be useful.
• DocBook XSL: The Complete Guide discusses how to XSL Transform your DocBook sources to other formats.
• The HTML Parameter Reference discusses the option available of the XSL style sheets provided by Norman Walsh.
• Globus Documentation Primer provides a good overview of DocBook elements. Most of this has been absorbed into this guide.