This section describes how to install the free processors. The commercial processors are assumed to provide instructions and support. You should check the details with each product that is described here, as the steps may change over time.
The installation of xsltproc is platform dependent since it is a compiled C program. You will need a C compiler and associated Make tools unless you are using Windows. Macintosh users can download binaries from http://www.zveno.com/open_source/libxml2xslt.html.
You can download precompiled versions for Windows from Igor Zlatkovic's website: http://www.zlatkovic.com/libxml.en.html
That page also describes how to install the files and use xsltproc on Windows. You need to download the packages for
iconv. They arrive as
.zip files which can be unpacked with any of the zip utilities on Windows.
Once you have unpacked them, your environment's
PATH variable must include the locations of the command files like
xsltproc.exe and the set of library files named with the
.dll suffix. Since they install into separate directories, you may need to add several
PATH entries. So it is perhaps simplest to just copy all the files into a single location already in the
PATH. For example, find and copy thefollowing files into
You will know it is working if you can execute the following command in a Command shell to list the version information:
Cygwin is a Linux-like environment that runs on Windows. It gives you the same command shells and utilities that are available on Linux systems. If you are comfortable with Linux, then you can have it on Windows too. There is a version of xsltproc for Cygwin.
If your Windows machine is connected to the Internet, then go to this website:
You will see information for installing Cygwin over the Internet. The complete Cygwin collection of packages is big, so it might take a long time over a slow connection. You can select only the packages you need. Read the directions for understanding the GUI interface used by the Cygwin setup. The two packages you must have are
libxslt, both available under the
Libs category. You should also install one of the shells such as
Once you have installed the packages, you should be able to start a Cygwin shell and execute this command to see the version installed:
If you are running a recent vintage of Linux, there is a good chance you will already have xsltproc installed on your system. Try the following command to see if you do:
You need system administration privileges (root) to install packages. Then commands such as these should work:
rpm -Uv libxml2-2.6.16-1.i386.rpm rpm -Uv libxslt-1.1.15-1.i386.rpm
xsltproc -version to see if it reports the new version number.
If you cannot find a precompiled version of xsltproc for your platform, or if you want the very latest version, then you can compile it yourself from source. It is pretty easy to compile xslproc if you use the GNU compiler. That compiler is generally available on all Linux distributions, and is also available for many Unix systems. It is even available for Cygwin (a Linux environment that runs on Windows). You might need to search the Internet to find one for your system if it doesn't already have one.
Once you have gcc set up, download and unpack the latest xsltproc source archives from
http://xmlsoft.org/XSLT/ (unless you are compiling under Cygwin, in which case you should download the source from the Cygwin archive). To run the xsltproc processor, you need the
libxslt packages, the ones with the highest version numbers. Then do the following:
Unpack the distribution archives (the version numbers will be different from this example):
tar zxvf libxml2-2.6.16.tar.gz tar zxvf libxslt-1.1.15.tar.gz
cd libxml2-2.6.16 ./configure make make install
You will need to have root permission to run the install step.
cd libxslt-1.1.15 ./configure make make install
You will need to have root permission to run the install step. If these steps proceed without error, you should be able to run this command to test it:
If you get a
Command Not Found error message, then you need to find where xsltproc is
installed and add that location to your
PATH environment variable.
General usage: xsltproc \ [
options] \ [--stringparam
name value] \
xml-documentHTML example: xsltproc \ --output myfile.html \ --stringparam use.extensions 0 \ docbook-xsl/html/docbook.xsl \ myfile.xml FO example: xsltproc \ --output myfile.fo --stringparam use.extensions 0 \ docbook-xsl/fo/docbook.xsl \ myfile.xml
You can place any options such as
xsltproc. The options are listed at
http://xmlsoft.org/XSLT/xsltproc2.html. You can use any number of
--stringparam options to pass stylesheet parameter values on the command line, in this case setting the parameter named
use.extensions to a value of
0 (because xsltproc cannot use the Java stylesheet extensions). If a parameter value includes spaces or special characters, put it in quotes.
Two xsltproc options you do not want to
use with DocBook are
--html which is for HTML input, and
--docbook which is for DocBook SGML input, not
If you don't like using a command line interface, you can download the free tkxsltproc from http://tclxml.sourceforge.net/tkxsltproc.html. It is a graphical interface to xsltproc that lets you browse for filenames and set options and parameters.
This is the full version of Saxon that implements the XSLT 1.0 standard. It runs on any Java-capable system, and provides opportunities for adding extensions. It is probably the most commonly used Saxon package, and is the version used in the examples in this book.
The Instant Saxon processor is a precompiled version of Saxon 6.5.3 that runs only on Microsoft Windows. Instant Saxon relies on the Microsoft Java VM, which is no longer shipped with Windows XP but can be separately downloaded from Microsoft.
This is the open source version of Saxon 8 that supports the emerging XSLT 2.0 standard, as well as several other new XML standards. It is under active development, as are several of the standards that it implements.
This is the commercial version of Saxon 8. The SA stands for “schema aware”, because it implements the W3C XML Schema standard.
Some people choose to replace the XML parser that is included with Saxon with the Xerces XML parser, which provides additional features. That optional step is included here too.
Update your Java
Saxon is a Java-based XSLT processor. So your system must have a Java processing environment for it to work. Java version 1.3 and higher is recommended for processing speed, which is a significant consideration for DocBook XSL because the stylesheets are big.
You can find out which Java is on your system by executing java -version. If you get
Command not found then you may not have Java installed on the system, or it
may not be in your PATH. Java version numbering has evolved over the years. Here is a current rundown of Java versions:
The Java runtime system is available for download from Sun Microsystems, Inc. for Windows, Linux, and Sun Solaris. If you have a different platform (UNIX or Mac, for instance), then you need to contact your OS vendor to see if they make available an up-to-date Java runtime environment. You are looking for the Java 2 Platform Standard Edition (J2SE).
Download full Saxon 6.5.3
To download Saxon, go to http://saxon.sourceforge.net/ and locate the full (not Instant) 6.5.3 version for download.
Unpack the archive
Saxon is distributed as a zip file, so you need to unzip it into some suitable location. It can be a temporary location because you can move the few files you really need to a new location.
Locate the Saxon .jar files
To run Saxon, you only need to tell your Java processor where the Saxon .jar files are. There are three files in the directory you unpacked Saxon into:
The Saxon XSLT processor.
Classes for integrating Saxon with FOP within a Java application.
Classes for integrating Saxon with JDOM.
You won't need
saxon-jdom.jar for use with the DocBook XSL stylesheets.
Locate the DocBook Saxon extensions file
The DocBook stylesheets have some custom extension functions
written specifically for the Saxon processor. These functions are
contained in a
saxon653.jar file that is included with the DocBook
distribution in its
There may be several saxon jar files there, labeled by the version number
of Saxon. Use the one closest to your Saxon version number. See the section “DocBook Saxon extensions” for a more complete description of the DocBook Saxon extensions.
(Optional) Download Xerces XML parser
If you want to use the Xerces XML parser in place of the default Saxon parser, download the Xerces parser from http://xml.apache.org/xerces2-j/. You want the Xerces2 Java parser. The web page has a link to where you can download just the latest jar file,
xercesImpl.jar. Put the file in a convenient location. See the section “Using the Xerces parser with Saxon” to get it working.
Update your CLASSPATH
You need to include the full path to the necessary
.jar files (described above)
in your CLASSPATH environment variable. That environment variable is used by the Java processor to locate compiled code used by Java programs. You can copy the
.jar files to a
convenient location (perhaps where other jar files are stored) before
specifying that location in your CLASSPATH.
To update your CLASSPATH on Linux, put these lines in your
.profile file, changing the pathnames to match the locations on your system:
CLASSPATH=$CLASSPATH:/usr/saxon/saxon.jar:\ /usr/docbook-xsl/extensions/saxon653.jar export CLASSPATH
If you want to use the Xerces XML parser, then include the path to
CLASSPATH=$CLASSPATH:/usr/saxon/saxon.jar:\ /usr/docbook-xsl/extensions/saxon653.jar:/usr/share/xercesImpl.jar export CLASSPATH
Use the Windows Control Panel to open the System icon.
Select the Advanced tab, and then the Environment Variables button.
In the System Variables list, scroll to the CLASSPATH variable if it exists and select Edit. If it does not already exist in the list, then select New.
The Variable name is
CLASSPATH. The Variable value for CLASSPATH is a single string containing a sequence of directory paths separated by semicolons. Each path should be a full path to one of the required
.jar files. For example:
Choose OK to close the dialog boxes and exit the System utility.
If you are already in a DOS window, you will need to exit and restart it for the new environment variable to take effect.
You can tell if your Saxon processor is working by exectuting the following command:
java com.icl.saxon.StyleSheet -t
This should report the version of Saxon that you have installed, as well as usage and command options. If instead you get an error message about
NoClassDefFoundError, then your CLASSPATH is not set correctly.
Saxon is a Java application that is executed from a command line. In order for the command to find all the Java code it needs, you must add the
.jar files described above to your
CLASSPATH environment variable. Once you have done that, then you execute the java command as follows. The backslashes mean the line continues without break, but is shown here on separate lines for clarity.
General syntax: java com.icl.saxon.StyleSheet \
param=valueHTML example: java com.icl.saxon.StyleSheet \ -o myfile.html \ myfile.xml \ docbook-xsl/html/docbook.xsl \ use.extensions=1 FO example: java com.icl.saxon.StyleSheet \ -o myfile.fo \ myfile.xml \ docbook-xsl/fo/docbook.xsl \ use.extensions=1
Note that the XML document name precedes the stylesheet path in a Saxon command line. You can put any Saxon options such as
-o before the document filename. The possible options are listed at http://saxon.sourceforge.net/saxon6.5.2/using-xsl.html. You can also set any number of stylesheet parameters such as
use.extensions=1 after the stylesheet path. See Chapter 5, Using stylesheet parameters for details on using parameters.
The XML parser that comes with Saxon has limited features, so many people choose to substitute the Xerces XML parser when using Saxon. The section on installing Saxon included an optional step for downloading the Xerces parser. Once you have added the path to
xercesImpl.jar to your CLASSPATH, you just need to add a couple of options to the Saxon command line:
Saxon with Xerces parser: java \ -Djavax.xml.parsers.DocumentBuilderFactory=\ org.apache.xerces.jaxp.DocumentBuilderFactoryImpl \ -Djavax.xml.parsers.SAXParserFactory=\ org.apache.xerces.jaxp.SAXParserFactoryImpl \ com.icl.saxon.StyleSheet \ -o myfile.html \ myfile.xml \ docbook-xsl/html/docbook.xsl
-D options must appear before the
com.icl.saxon.StyleSheet class name. The options will fail if the
xercesImpl.jar file is not included in the CLASSPATH.
The DocBook XSL distribution comes with a set of extensions to the Saxon XSLT processor. These extensions are Java programs that provide functions that are not part of the XSLT standard. The DocBook Saxon extensions are contained in the file
extensions/saxon653.jar. To make the extensions available to the stylesheets, you have to include this file in your Java CLASSPATH, as described in the section “Installing Saxon”.
The DocBook Saxon extensions are not enabled by default. They are enabled by setting various stylesheet parameters. See Chapter 5, Using stylesheet parameters to learn how to set stylesheet parameters. You must set the
use.extensions parameter to 1 to enable any of the extensions, then you
must also set individual parameters for each extension function.
The following is a list of the functions and their enabling
|Stylesheet parameter||Function||More information|
|Positions callout markers in ||See the section “Callouts on imported text”.|
|Imports a text file into an example and escapes any characters that would otherwise be interpreted as markup.||See the section “External code files”.|
|Adjusts the widths of table columns to better match the CALS table specifications.||See the section “Column widths”.|
|Displays line numbers at the beginning of line in a ||See the section “Line numbering”.|
|Computes the intrisic size of images to help size the image for HTML output. Not used for print output.||See the section “ Image sizing”.|
If you are not using any of these features in your documents, then you have no need to turn on the extensions. However, there is no harm in turning them on. A similar set of extensions exists for the Xalan processor, but not for any others.
Xalan's installation process depends on which version of the Java runtime you will be using to run it. In Java 1.4, a version of Xalan was bundled into the runtime. Unfortunately, the version that was bundled was superceded by improved versions from Apache.org. Most people preferred the newer versions, but they required taking some extra steps to make sure the bundled version wasn't being used instead. In the following procedure, any extra steps needed for Java 1.4 are called out.
Xalan is very easy to install because it is a Java program and requires no compiling. It will run on any Java platform, including Linux, Windows, and UNIX.
Update your Java
Since Xalan-J requires a Java runtime environment, you might need to obtain or update your Java setup before Xalan will work. See the step on updating Java in the section “Installing Saxon”.
Be sure to get the Xalan Java version, not the Xalan C++ version. To download Xalan-J, go to
and locate the latest stable binary version for download. You probably
won't want the latest experimental version. They provide .zip files with everything you need. That site will also provide you with detailed instructions for getting started with Xalan. As of version 2.5.1 of Xalan, it is available in two binary distributions. In one, the Xalan Compiled processor (XSLTC) is included in
xalan.jar, and in the other, it is not. Either one will work for DocBook processing. If you want to take advantage of XSLTC, see http://xml.apache.org/xalan-j/xsltc_usage.html.
Unpack the archive
Xalan is distributed as a zip file, so you need to unzip it into some suitable location. It can be a temporary location because you can move the few files you really need to a new location.
Locate the Xalan .jar files
To run Xalan, you only need to tell your Java processor where
.jar files are. The
bin directory in the directory you
unpacked Xalan into will contain the three files you need:
xalan.jar xml-apis.jar xercesImpl.jar
Here is what all the files are for:
The main Xalan XSLT processor.
The XML parser used to parse the XML file.
Provides the SAX, DOM, and JAVAX interfaces used by Xalan.
A set of sample Java applications using Xalan. This file is not needed for DocBook processing.
Sample application using Xalan in a Java servlet. This file is not needed for DocBook processing.
Bundled set of XSLTC functions for compiling XSL stylesheets into a set of Java classes. This file is not needed for DocBook processing. It may not be present, depending on which package of Xalan you downloaded.
The following additional
.jar files may be included with your Xalan distribution. Most are the unbundled XSLTC functions that are now available as a bundle in
xsltc.jar. They are not needed for DocBook processing.
BCEL.jar JLex.jar bsf.jar java_cup.jar regexp.jar runtime.jar
Locate the Xalan DocBook extensions file
The DocBook stylesheets have some custom extension functions
written specifically for the Xalan processor. These functions are
contained in a
xalan25.jar file that is included with the DocBook
distribution in its
If your version of Xalan is earlier that 2.5, then use the
xalan2.jar file instead.
Install the .jar files
Your version of Java determines where the main
xalan.jar file is installed.
If you have Java version 1.4, you need to put the Xalan jar files in the
lib/endorsed directory under your Java distribution. For example, if your Java is installed under
/usr/jre2, then copy the Xalan files into
/usr/jre2/lib/endorsed. Then the new Xalan will be used in place of the built-in Xalan that comes with Java 1.4. If you don't have write permission to the Java installation directory, you can use a different method as described in the section “Bypassing the old Xalan installed with Java”.
If you don't register the newer Xalan as the “endorsed” version, then your processing will use the older version of Xalan and you may not get the results you expected.
If your Java is not version 1.4 (version 1.3 or below or 5.0 or later), then you can put the jar files in any convenient location for creating a CLASSPATH. You don't have to worry about the Java endorsing process.
Update your CLASSPATH
To update your CLASSPATH on Linux, put these lines in your
CLASSPATH=$CLASSPATH:/usr/Xalan/xalan.jar:/usr/Xalan/xml-apis.jar:\ /usr/Xalan/xercesImpl.jar:/usr/docbook-xsl/extensions/xalan25.jar export CLASSPATH
On Windows, use the Control Panel to open the System icon, where you can set environment variables for Windows. Use semicolons instead of colons to separate items in the CLASSPATH.
bsf.jar file (Bean Scripting Framework) is used to
support XSLT extensions written in languages other than
Java. Since Norm Walsh wrote the DocBook extensions for Xalan
in Java, you don't need to include
bsf.jar in your CLASSPATH for DocBook.
But you may want it for other stylesheets.
You can tell the Xalan processor is working by running this command:
Like Saxon, Xalan is a Java application, so you need to set the
CLASSPATH environment variable as described in the section “Installing Xalan”. Then you can execute the Xalan java command that includes a stylesheet, an input filename, and any number of Xalan options.
General syntax: java org.apache.xalan.xslt.Process \ -out
name valueHTML example: java org.apache.xalan.xslt.Process \ -out myfile.html \ -in myfile.xml \ -xsl docbook-xsl/html/docbook.xsl \ -param use.extensions 1 FO example: java org.apache.xalan.xslt.Process \ -out myfile.fo \ -in myfile.xml \ -xsl docbook-xsl/fo/docbook.xsl \ -param use.extensions 1
With Xalan, all the arguments to the command are entered as options, and the order of the options does not matter. The Xalan options are listed at http://xml.apache.org/xalan-j/commandline.html. You can set any number of stylesheet parameters with multiple
-param options. In this example, the parameter named
use.extensions is set to a value of
1. If a parameter value includes spaces or special characters, put it in quotes.
If for some reason Xalan doesn't work, you may need to know what version of Xalan and Java you are running to track down the problem. The following command will provide that information:
If you are running Java 1.4, an older version of Xalan is bundled with Java. You will want to download and install a newer version of Xalan. Unfortunately, just setting your CLASSPATH to the new jar files is not sufficient. You also need to supply a Java option to force it to use the newer versions.
CLASSPATH=$CLASSPATH:/usr/Xalan/xalan.jar:/usr/Xalan/xml-apis.jar:\ /usr/Xalan/xercesImpl.jar:/usr/docbook-xsl/extensions/xalan25.jar export CLASSPATH java -Djava.endorsed.dirs=/usr/Xalan \ org.apache.xalan.xslt.Process \ -out myfile.html \ -in myfile.xml \ -xsl /docbook-xsl/html/docbook.xsl
java.endorsed.dirs option tells Java it is ok to use the jar files contained in the specified directory. You could also install the Xalan jar files into
directory, in which case you don't need to supply the command line option. Here
javahome is the directory where the runtime software is installed (which is the top-level directory of the Java 2 Runtime Environment or the
jre directory in the Java 2 SDK).
See http://java.sun.com/j2se/1.4.1/docs/guide/standards/ for more information on the endorsed override mechanism in Java.
The DocBook XSL distribution comes with a set of extensions to the Xalan XSLT processor. These extensions are Java programs that provide functions that are not part of the XSLT standard. The DocBook Xalan extensions are contained in the file
extensions/xalan25.jar. To make the extensions available to the stylesheets, you have to include this file in your Java CLASSPATH, as described in the section “Installing Xalan”.
For a description of the available functions and how you enable them, see the section “DocBook Saxon extensions”, which describes the equivalent extensions for Saxon.
|DocBook XSL: The Complete Guide - 3rd Edition||PDF version available|
Copyright © 2002-2005 Sagehill Enterprises