This appendix demonstrates how DocBook tags are used and what their effect is (useful for testing how they render to other formats). This is a DocBook cookbook - it is it intended to be a complete DocBook reference. For a more complete description of how docbook may be used see here. 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.

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.0. 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.

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 done at chapter level. It may be advantageous at some later point to break this down to sections but we shall see how the present granularity works.

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.

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.

Some hints about changing the typography of text:

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:

Hector is the OGSA-DAI logo caption.

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

	Important
	Currently 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).

One can add an index entry by placing the following markup 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 for this document.

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 allows admonitions to be created to give warnings, tips, cautions, ..., etc. The colours used are determined in the default.css stylesheet.

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

Which renders to:

	Important
	Do not deliver results via SOAP.

while:

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

Gives:

	Warning
	Do not deliver results via SOAP.

and

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

gives:

	Note
	Do not deliver results via SOAP.

and

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

gives:

	Tip
	Do not deliver results via SOAP.

with:

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

giving:

	Caution
	Do not deliver results via SOAP.

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.

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^[6] can decorate almost all DocBook defined elements. These can then be used for conditional compilation to obtain particular views of the documentation.

For 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.

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