Building the documentation

In order to build the documentation it is necessary to have the DocBook5 XSL stylesheets installed together with "xsltproc" which is used to transform the source into various output formats. In addition, to build the versions (either HTML or PDF) that supports highlighting of included source (within the <programlisting> element) the Saxon 6.5.5 XSL processor must be used. This is necessary since the syntax highlighting in DocBook is based on a Java extension (xslthl-2.x.x) which requires a Java based processor (such as Saxon).

Tip

The easiest way to setup a complete build environment for DocBook5 for people new to DocBook is to install a clean version of Debian 7.x and then run the "deb-setup.sh" shell script. This will create a fully tested and working build environment for DocBook5 as it is used with Phing. This could easily be done using a virtual setup (for example using VirtualBox).

All DocBook sources are structured in a tree under docs/docbook5. The top level is the language of the manual. As of this writing only an English manual is available and hence the only top level directory available is "en". Under this directory the following structure applies (also for any new language translation that is added):

├── scripts
├── source
│   ├── appendixes
│   └── chapters
└── stylesheets
    ├── css
    │   └── img
    └── xsl
        └── images

All document sources are stored under the subdirectory "source" and the master document is aptly named "master.xml". This document pulls in all chapters and appendixes in the right order. For example, new tasks added should normally be documented in the "appendix/optionaltasks.xml" file. Look at the existing tasks and follow the same structure.

Important

In order to get highlighting to work both the "xslthl-2.x.x.jar" package must be installed as well as Saxon 6.5.x. The jar file must be installed somewhere in the CLASSPATH , for example "/usr/share/java" if you run this on Linux. The xslthl package is available on SourceForge, please see XSLT syntax highlighting. By using the automated setup for Debian 7.x all these dependencies will be taken care of!

The customized stylesheets used are stored under "stylesheets" which uses one sub-folder for the customized XSL stylesheets (responsible for the transformation from DocBook to the chosen output format) and one sub-folder for the CSS stylesheets used to give the generated HTML documents there "look & feel".

Finally the "scripts" directory stores utility scripts. This currently contains two scripts, deb-setup.sh and "hlsaxon". The first scripts helps to create a full build environment for DocBook5 starting with a clean Debian 7 installation. This is meant to help people new to DocBook5 to get a working build environment as easy as possible. This script takes care of all detailed setup and will make a fulloy working DocBook5 build environment out-of-the-box.

The second script (hlsaxon) is wrapper file used from the buildfiles to call the Saxon translator (a Java based XSL procesor) with highlighting enabled and suitable paths to supporting libraries In this script the path to the DocBook installed stylesheets must be adjusted depending on your system (unless the automated setup have been used - with the deb-setup.sh file which takes care of that setup automatically). Mutatis mutandis.

In order to drive the transformation a Phing build script is available in the docbook root, build.xml. The build script supports the following public targets

 all*         Builds all available targets (default)
 chunk        Builds the chunked HTML
 clean        Removes all output files
 epub         Builds the EPUB version
 hlhtml       Builds the HTML version with syntax highlight
 hlpdf        Builds the PDF version with syntax highlight   
 html         Builds the HTML version  
 htmlfancy    Builds the HTML version with an alternative styling for screen output
 pdf          Builds the PDF version
 webhelp      Builds the webhelp version (Note: This requires Java and Ant to be installed!)
 validate     Validates all sources against the DocBook5 grammar

All generated output is stored under the directory "output" (which is created if it doesn't exist) with a subdirectory corresponding to the name of the chosen output format.