Development Environment

To make full use of the project sources you need to install some tools and configure your system environment.

The majority of the tools used are Java. You will therefore need at least a Java 2 Runtime Environment, Standard Edition installed, version 1.4.2 or higher will be enough.

We use the following core components in our publishing tool chain:

• Docbook DTD V4.3

• Docbook XSL V1.66.1 or higher

• SAXON V6.5.3

• Apache FOP V0.20.5

Two Docbook customization layers are provided in the root of "src/".

• html-cust.xsl
• fo-cust.xsl

Both these files are used to customize the behaviour and output of the transformations created in the project make system.

Since the Docbook XSL Stylesheets are not distributed with the project sources, you will need to modify the "xsl:import" commands to point to your installation of the Docbook Stylesheets.

The current value of the "xsl:import" "@href" attribute is set to the default path defined as standard for most updated Linux distro's.

For HTML the value is:

<xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh/current/html/docbook.xsl"/>

For FO the value is:

<xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh/current/fo/docbook.xsl"/>

Alternately, you may map the current value of "@href" using an XML Catalog.

The projects' make system expects to find several java files in your "CLASSPATH".

If these resources are not already defined in your environment, export their locations:

CLASSPATH=$CLASSPATH:/usr/share/saxon-6.5.3/saxon.jar:/usr/share/xml/docbook/stylesheet/nwalsh/current/extensions/saxon65.jar:/usr/share/java/fop-0.20.5/build/fop.jar:/usr/share/java/fop-0.20.5/lib/batik. jar:/usr/share/java/fop-0.20.5/lib/xalan-2.4.1.jar:/usr/share/java/fop-0.20.5/lib/xercesImpl-2.2.1.jar:/usr /share/java/fop-0.20.5/lib/JimiProClasses.jar:/usr/share/java/fop-0.20.5/lib/avalon-framework-cvs-20020806. jar export CLASSPATH

You may use any XML editor for authoring. For a list of Docbook Authoring Tools see the Docbook Wiki.

Please take caution with some structured XML editors. Unless configured correctly, they do not preserve the whitespace and structure of XML documents. This results in additional whitespace being added to your file and entities being expanded into the XML structure.

If you intend submitting patches, this will result in huge differences between the repository revision and the working copy. Patches will therefore include your changes, additional whitespace and expanded content of entities.

For this reason we recommend using a source view XML editor such as emacs, vi, kate, or oxygen. If you wish to use a structured XML editor please ensure that you disable the features that cause these unwanted changes.