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.
O.2. 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.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.
O.3. Documentation Structure
O.3.1. Introduction
Currently documentation is processed using xsltpro. This is invoked through a Makefile with a number of targets: all, developer, user and product. These are different views of the documntation. 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, hope to have pdf, xhtml, etc. views of the documentation.
O.3.2. Directory Structure
Caution
This section is out of sync with what is actually in the file system. Will be updated or removed.
The directory structure for the documentation is as follows:
Directory containing files pertaining to the Administration view of the OGSA-DAI documentation.
Directory containing files pertaining to the Developer view of the OGSA-DAI documentation.
Directory containing files pertaining to a general view of the OGSA-DAI documentation.
Output directory where the processed conent will go.
Directory containing files pertaining to the User view of the OGSA-DAI documentation.
Directory containing image files.
Directory containing css files for the html produced. These are the same as used for the OGSA-DAI web site with a couple of additions for DocBook generated content.
Directory containing the XSL files produced by Norman Walsh available from the DocBook Source Forge project. The version currently being used is 1.72.0.
O.3.3. File Structure
There are a number of content files which are:
User.xml
Contains pointers to the User view of the documentation. Corresponding files are contained in the User subdirectory and some from the Misc subdirectory which have more general scope.
Developer.xml
Contains pointers to a Developer orientated view of the the documentation. Most of the relevant files are in the Developer subdirectory.
Administrator.xml
Has an administrator view of the documentation. Files are in the Administrator subdirectory.
All.xml
Contains all the documentation but processing at the moment is clobbering files so only the Developer view is coming out.
Product.xml
Is another view of the documentation.
These include other files using xinclude (see below) to pull in a number of files stored in the above directories to for documentation views.
Each of the files stored in the sub directories constitutes a chapter. That is the current granularity of the decomposition - at some future point it may be worthwhile having a section to a file but we shall see how well the current set up works.
Typically each of the chapter files has the following structure:
%myents;
]>
Title for my ChapterSection TitleThis is a sub section
Some content at last ...
O.4. Using of 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:
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:
Failure to include FileToBeIncluded.xml. Please fix!
This way you will have some warning that something has gone wrong.
This is the title for the OGSA-DAI Logo.This goes in the image ALT tag.
Hector is the OGSA-DAI logo caption.
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).
O.9. Image Guidelines
O.9.1. Image Package to Use
The recomended image package to use for images is DIA.
O.9.2. Diagram Layout
Some guidelines about layout:
Ensure layout is consistent, e.g. service components on the right clients on the left, etc.
To add an informal table you can use the following pattern:
header1header2header3a1b1c1a2b2c2a3b3c3
Which 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.
O.10.2. 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).
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:
Links to the beginning of the section Section O.11, ?Adding Links?, 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:
One can add an index entry by placing the following markup in your content:
IndexEntrySubentry
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.
O.13. Adding Glossary Entries
Glossary entries are stored in Misc/Glossary.xml. To add an entry use:
DefinedTerm
Term definition
This can then be referenced from the main body of the text by using:
DefinedTerm
O.14. DocBook Admonitions
DocBook allows admonitions to be created to give warnings, tips, cautions, ..., etc. The colours used are determined in the default.css stylesheet.
Do not deliver results via SOAP.
Which renders to:
Important
Do not deliver results via SOAP.
while:
Do not deliver results via SOAP.
Gives:
Warning
Do not deliver results via SOAP.
and
Do not deliver results via SOAP.
gives:
Note
Do not deliver results via SOAP.
and
Do not deliver results via SOAP.
gives:
Tip
Do not deliver results via SOAP.
with:
Do not deliver results via SOAP.
giving:
Caution
Do not deliver results via SOAP.
O.15. 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.
O.16. 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[6] 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.
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:
For OGSA-DAI GT we do...
For OGSA-DAI Axis we do...
For OGSA-DAI GT we do...
For OGSA-DAI Axis we do...
The phrase element is useful for grouping multiple elements
relating to OGSA-DAI GT...
Like this...
And likewise for OGSA-DAI Axis...
Like this...
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.
O.17. Further Sources of Information About DocBook
The following sources may provide further information about DocBook that may prove to be useful.
Docbook: The Definitive Guide is an OReilly 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.