Installing an XSLT processor

Installing an XSLT processor
	Chapter 3. Getting the tools working

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.

Installing xsltproc

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.

Installing xsltproc on Windows

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 libxml, libxslt, zlib, and 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 C:\Windows\System32:

`libxslt.dll`	`iconv.dll`	`xmllint.exe`
`libxml2.dll`	`zlib.dll`
`libexslt.dll`	`xsltproc.exe`

You will know it is working if you can execute the following command in a Command shell to list the version information:

xsltproc -version

Installing xsltproc on Cygwin

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:

http://www.cygwin.com/

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 libxml2 and libxslt, both available under the Libs category. You should also install one of the shells such as bash.

Once you have installed the packages, you should be able to start a Cygwin shell and execute this command to see the version installed:

xsltproc -version

Installing xsltproc on Linux

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:

xsltproc -version

If that command fails, or if it reports an old version, you can install the files you need using the RPM packages. The RPM packages can be found using the following URLs:

http://rpmfind.net/linux/rpm2html/search.php?query=libxml2
http://rpmfind.net/linux/rpm2html/search.php?query=libxslt

You need system administration privileges (root) to install packages. Then commands such as these should work:

rpm -Uv libxml2-2.6.27-1.i386.rpm
rpm -Uv libxslt-1.1.20-1.i386.rpm

Then try xsltproc -version to see if it reports the new version number.

Compiling xsltproc

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 does not 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 libxml2 and 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.27.tar.gz
tar zxvf libxslt-1.1.20.tar.gz
```
Compile libxml2:
```
cd libxml2-2.6.27
./configure
make
make install
```
You will need to have root permission to run the install step.
Compile libxslt:
```
cd libxslt-1.1.20
./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:
```
xsltproc -version
```

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.

Using xsltproc

To use xsltproc, you specify the location of the main stylesheet file and your DocBook document, as well as any options and parameters:

General usage:
xsltproc  \
    [options]  \
    [--stringparam name value]  \
    stylesheet-path  \
    xml-document 

HTML 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 --output after 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.

Note

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 XML input.

If you do not 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.

Installing Saxon

Saxon is a Java-based XSLT processor that is well respected for its adherence to the XSLT standard. Currently Saxon is available in four packages:

Saxon 6.5.5: 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.
Instant Saxon 6.5.3: 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.
Saxon-B 8: 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.
Saxon-SA 8: 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 environment variable. Java version numbering has evolved over the years. The following table lists past and current Java versions:
Table 3.2. Java versions
Product name Java Versions
Java
1.0 1.1
Java 2
1.2 1.3 1.4
Java 2 Platform, Standard Edition 5.0 (J2SE 5.0)
1.5
Java Platform, Standard Edition 6 (Java SE 6)
1.6
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.5
To download Saxon, go to http://saxon.sourceforge.net/ and locate the full (not Instant) 6.5.5 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:
saxon.jar
The Saxon XSLT processor.
saxon-fop.jar
Classes for integrating Saxon with FOP within a Java application.
saxon-jdom.jar
Classes for integrating Saxon with JDOM.
You will not need saxon-fop.jar or 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 extensions subdirectory. 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 and Xalan 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 xercesImpl.jar:
```
CLASSPATH=$CLASSPATH:/usr/saxon/saxon.jar:\
/usr/docbook-xsl/extensions/saxon653.jar:/usr/share/xercesImpl.jar
export CLASSPATH
```
To update your CLASSPATH on Windows, do the following:
1. Use the Windows Control Panel to open the System icon.
2. Select the Advanced tab, and then the Environment Variables button.
3. 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.
4. 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:
```
c:\saxon\saxon.jar;c:\docbook-xsl\extensions\saxon653.jar
```
5. Choose OK to close the dialog boxes and exit the System utility.
6. If you are already in a DOS window, you will need to exit and restart it for the new environment variable to take effect.

Product name	Java Versions
Java	1.0 1.1
Java 2	1.2 1.3 1.4
Java 2 Platform, Standard Edition 5.0 (J2SE 5.0)	1.5
Java Platform, Standard Edition 6 (Java SE 6)	1.6

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.

Using Saxon

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 Java .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 \
    options  \
    xml-document  \
    stylesheet-path  \
    param=value

HTML 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 6, Using stylesheet parameters for details on using parameters.

Using the Xerces parser with Saxon

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

These -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.

DocBook Saxon and Xalan extensions

The DocBook XSL distribution comes with a set of extensions to the Saxon or Xalan XSLT processors. 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/saxon65.jar, and the Xalan extensions are in extensions/xalan.27 (or the latest version). 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 and Xalan extensions are not enabled by default. They are enabled by setting various stylesheet parameters. See Chapter 6, Using stylesheet parameters to learn how to set stylesheet parameters. Each extension has its own stylesheet parameter, and they are all set to 1 (on) by default. However, they are not actually turned on by default because the overall use.extensions parameter that enables all of them is set to zero (off) by default. To use any of the extensions, set the use.extensions parameter to 1. The following is a list of the functions and their enabling parameters.

Stylesheet parameter	Function	More information
`use.extensions`	When set to zero, disables all of these extensions. Set it to 1 to use any of these extensions. Default value is zero.
`callouts.extension`	Positions callout markers in `programlistingco` and `screenco` based on the area coordinates. The default value is 1.	See the section “Callouts on imported text”.
`textinsert.extension`	Imports a text file into an example and escapes any characters that would otherwise be interpreted as markup. The default value is 1.	See the section “External code files”.
`tablecolumns.extension`	Adjusts the widths of table columns to better match the CALS table specifications. The default value is 1.	See the section “Column widths”.
`linenumbering.extension`	Displays line numbers at the beginning of line in a `programlisting`, when it has a `linenumbering="numbered"` attribute. The default value is 1.	See the section “Line numbering”.
`graphicsize.extension`	Computes the intrisic size of images to help size the image for HTML output. Not used for print output. The default value is 1.	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.

Installing Xalan

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 was not 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”.
Download Xalan
Be sure to get the Xalan Java version, not the Xalan C++ version. To download Xalan-J, go to http://xml.apache.org and locate the latest stable binary version for download. You probably will not 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 the Xalan .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:
xalan.jar
The main Xalan XSLT processor.
xercesImpl.jar
The XML parser used to parse the XML file.
xml-apis.jar
Provides the SAX, DOM, and JAVAX interfaces used by Xalan.
xalansamples.jar
A set of sample Java applications using Xalan. This file is not needed for DocBook processing.
xalanservlet.jar
Sample application using Xalan in a Java servlet. This file is not needed for DocBook processing.
xsltc.jar
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. See the section “DocBook Saxon and Xalan extensions” for details. These functions are contained in a file named xalan27.jar (or the latest version) that is included with the DocBook distribution in its extensions subdirectory. If your version of Xalan is earlier that 2.7, 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 do not 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”.
  Important
  If you do not 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 do not have to worry about the Java endorsing process.
Update your CLASSPATH
You need to include the full path to .jar files in your CLASSPATH environment variable.
To update your CLASSPATH on Linux, put these lines in your .profile file:
```
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.
The 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 do not 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:

java  org.apache.xalan.xslt.EnvironmentCheck

It reports on the Java environment and the version of Xalan. If you get a message about a class not found, then your CLASSPATH is not set up right to use Xalan.

Using Xalan

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 outputfile  \
    -in xml-document  \
    -xsl stylesheet-path  \
    -param name value

HTML 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 does not 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:

java  org.apache.xalan.xslt.EnvironmentCheck

Bypassing the old Xalan installed with Java

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

The 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 /javahome/lib/endorsed directory, in which case you do not 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.

DocBook Xalan extensions

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 and Xalan extensions”, which describes the equivalent extensions for Saxon.


Installing the DocBook stylesheets		Installing an XSL-FO processor