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.