2. Tools installation

Docbook XSL Stylesheet

There is a great reference for installing tools : Docbook XSL : the guide.

To write a manual using Docbook and the XSL stylesheets, we need four tools :

  • Docbook DTD

  • Docbook XSL stylesheets

  • XSL processor

  • XSL-FO processor (optional)

There are RPM (docbook-dtds, docbook-style-xsl), Debian (docbook-xml, docbook-xsl) packages for Linux systems, Fink packages for Mac systems, and Cygwin and other packages for Windows systems. The installation of Docbook and the XSL stylesheet create a file named /etc/xml/catalog. It contains the informations about all others catalogs to resolve the path of the DTDs and the stylsheets from the URI.

Manual Installation : Docbook XSL stylesheet

As we have some problems with the DTD provided by the distributions, Tulip gives the DTD 4.4 of Docbook XML and is located in $TULIPDIR/docs/common/dtd. So, this section is for informations. The XSL packages seem to have great catalog resolutions, but if you have problems, this section can help you.

If you need another solution or you have problems for the compilation, you can download the source package on oasis web site for Docbook and on the SourceForge page of XSL stylesheets. The Docbook sources are in a zip file. Unzip your package in a directory in the place you prefer. The Docbook XML DTD consists of a main file docbookx.dtd, several module files and a catalog file, named catalog.xml. To update the changes of location of your DTD, edit the file CatalogManager.properties in $TULIPDIR/docs/common/. Add the catalog file with its asbolute path to the catalogs variable.

CatalogManager.properties :

catalogs=/etc/xml/catalog;/home/bardet/docbook-4.4/catalog.xml
relative-catalogs=false
static-catalog=yes
catalog-class-name=org.apache.xml.resolver.Resolver
verbosity=1

Concerning the XSL stylesheet package, you just have to do the same thing. You can execute the script of intallation. You have to add the reference of the catalog too. Edit the file catalog.xml and complete the catalogs variable with the reference of the catalog of your XSL stylesheet. This catalog resolution make sure that the path, the differences could be find in all Operation Systems.

XSL processor

Currently, there are three to do XSL Transform processing with the recommendations of XSL : saxon (http://saxon.sourceforge.net/), xalan (http://xml.apache.org/xalan-j/), and xsltproc (http://xmlsoft.org/XSLT/xsltproc2.html). For the Tulip project, we have decides to use Saxon for the XSL processor. Xsltproc is the xslt c library for gnome. This program is a way to use the library libxslt with a command line tool for applying XSLT stylesheets to XML documents. This application runs quickly but does not include the implementation of the extensions. Xalan is an other solution but Saxon is the most recommanded.

Saxon is a free processor written in Java, so it can be run on any operating system with a modern Java interpreter. To install it, you have to download on sourceforge the last release 6.5.4. for debian, it exists a deb package. This is the full version that implements the XSLT 1.0 standard. It runs on Java system and provides opportunities for extensions. For Windows, it exists the Instant Saxon a precompiled version that runs only on Microsoft Windows. Saxon is distributed as a zip package. You have to unzip it into a suitable location. It gives three .jar files ; saxon.jar contains the XSLT processor. In according to the location, you have to update your CLASSPATH. You need to include the full path to the necessary .jar files in the CLASSPATH environment variable. To update it :

CLASSPATH=$CLASSPATH:/usr/saxon/saxon.jar:\
/usr/docbook-xsl/extensions/saxon653.jar
export CLASSPATH

If your CLASSPATH is incorrect, you get an error message about NoClassDefFoundError. To generalize it, you have to change your .bashrc or .bash_profile. In this example, a second package is included : /usr/docbook-xsl/extensions/saxon653.jar, in Fedora Core 4, it is located in /usr/share/sgml/docbook/xsl-stylesheets/extensions/. It contains the implementation of the extensions of XSL Transformations. This extensions are necessary to manage some tags and are included in the docbook tools. The general syntax for compilation is like followed :

java com.icl.saxon.StyleSheet [options] [file.docbook] [file.xsl] [param=value]

However, Tulip provides the sources of saxon and you do not worry to this installation to avoid the complicated installation.

Warning

This system of catalog resolution is made for finding located files. With the packages of Fedora and perhaps with others distribution, the catalogs include a declaration with URL adresses. So the catalog resolving processor try to connect on the Net.

<!DOCTYPE catalog PUBLIC "-//OASIS//DTD XML Catalogs V1.0//EN"
"http://www.oasis-open.org/commitees/entity/release/1.0/catalog.dtd">

It should be erased in all catalog files which blocks the offline compilation (/etc/xml/catalog, /usr/shar/sgml/docbook/xmlcatalog, ...).

XSL-FO processor for PDF output

To transform the docbook sources in pdf documents, we need to use an other format FO. It is running with a stylesheet in docbook-xsl package. The role of the XSF-Fo processor is to transform FO files in printable files, like pdf. You have to install passivetex. Fedora and Debian includes this package, but you can download and install it with its web site, http://www.tei-c.org.uk/Software/passivetex/. It exists a program named pdfxmltex giving tex macros for the XSL-Fo processing.

Doxygen

It can already be in your distribution. For distributions like Debian or Fedora Core, you can used :

yum [install doxygen]

apt-get [install doxygen]

For another solution, you can find source files and CVS repository in the web site of Doxygen (http://www.stack.nl/~dimitri/doxygen).