SCRIPT Notice
=============

This directory contain two custom script(s) one to setup a complete working
build environment for DocBook5 and one wrapper script to  make it easier to
build the version of the manual with the syntax highlighting enabled. 

deb-setup.sh
------------
This is a shell script meant to be run on a clen Debian 7 setup. The script
will install all necessary DocBook5 dependencies including th 1.78.1 DocBook5
stylesheets which is not yet available as a package for Debian.

After the script has been run it is possible to build all supported output
renderings of the manual.


hlsaxon script
--------------
This uses the highlight functionality available in docbook5 together which in
turn uses xslthl-2.x.x 

The xslthl-2.x.x must therefore be installed into the Java CLASSPATH. 
(Download from: http://sourceforge.net/projects/xslthl/files/xslthl )
If the deb-setup.sh script is used to setup the build-server this dependency
will already have been downloaded and installed.

Some general cautions (using the deb-setup.sh script takes care of all of these):

 * This script has only been tested on Debian 7 and OpenSuSE 12.2, 12.3 and
   depends specific paths to the stylesheets.

 * This assumes that the path to the DocBook stylesheets are

      /usr/share/xml/docbook/stylesheets/nwalsh5/current

   Mutatis mutandis.

 * Saxon 6.x.x Java xslt processor must be installed (and available in the
   Java CLASSPATH)

 * Depending on your system the necessary "saxon.jar" may be named "saxon6.jar" in which
   case you need to updated the script with the correct name. The same goes for the exact
   version of xslthl you have insatlled. As of this writing the latest version is 2.1.0

 * 'xmllint' must be available since that is used to pre-process the xinclude
   to create a flattened XML version of the manual.


Yes, all this is a PITA. But there is no other way to get easy Syntax highlight in DocBoook
besides rolling a completely homegrown solution which is probably even worse. One option
might be to use dynamic highlitning with Javascipt (i.e. JQuery) for the HTML rendering but 
that will not work for PDF output anyway.


