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 XSL stylesheets
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.
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
$TULIPDIR/docs/common/. Add the catalog file with its asbolute path to the
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.
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
.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] [
However, Tulip provides the sources of saxon and you do not worry to this installation to avoid the complicated installation.
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, ...).
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.
It can already be in your distribution. For distributions like Debian or Fedora Core, you can used :
For another solution, you can find source files and CVS repository in the web site of Doxygen (http://www.stack.nl/~dimitri/doxygen).