A.1 Installing and Running XSLT Processors

The following sections provide detailed information about how to download, install, and run five popular XSLT processors with command-line interfaces: Instant Saxon, Saxon, MSXSL, Xalan C++, and jd.xslt.

You also learn how to transform XML documents using the graphical tools xmlspy and xRay2. Both xmlspy and xRay2 are XML editors with XSLT capabilities and run only on Windows.

A.1.1 Installing and Running Java

As a first step, you need to get the latest version of the Java Runtime Environment (JRE) or SDK (which includes a JRE) on your machine. To do so, go to http://java.sun.com/downloads. A JRE provides a Java virtual machine (JVM), a Java interpreter (java), and other necessities, but not tools like the Java compiler javac or a JAR (Java Archive) tool such as jar. To get the JRE from the Sun Java site, search for JavaVM, click it, and then click the download button that appears. This will automatically download and install the latest JRE. If you already have the latest JRE installed, this will be detected and you will be alerted about it.

You can test to find out whether a JRE is working on your machine by typing this command at a command or shell prompt:

java -version

If you get something back like the following, you are in good shape:

java version "1.4.1_01" Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.1_01-b01) Java HotSpot(TM) Client VM (build 1.4.1_01-b01, mixed mode)

To get a Java SDK, search for the download of your choice on the Sun Java site, such as J2SE 1.4.1, and then select Allplatforms in the text pull-down box. Click the Go button. Under the SDK columns, click the Download link for the appropriate platform, such as Linuxself-extracting file. Fill out the information form if you wish, or just click the download link again. Accept the license by clicking the Accept button. Finally, click the download link, and save the archive to the directory of your choice. After downloading the archive file, follow the installation instructions provided by Sun. (These instructions may vary over time.)

A.1.1.1 Setting the path variable

After the installation is complete, you must place the Java bin directory in your path environment variable. You can add the location to the path using one of the following methods.

A.1.1.1.1 The path environment variable on Windows

Supposing the bin directory is located at C:\Java\j2sdk1.4.1_01\bin, on Windows, you could temporarily set the path environment variable at a command prompt with this line:

path %path%;c:\Java\j2sdk1.4.1_01\bin

This command adds the path C:\Java\j2sdk1.4.1_01\bin, which contains the executable file javac.exe, to your current path variable, represented by the substitution variable %path%.

Another method for amending your path variable is adding this command line to your autoexec.bat file so that the new path is set each time you boot your computer.

On Windows 2000 or XP Professional, you can also set the path variable by choosing Start Control Panel System Advanced Environment Variables, and then adding the path to your user or system variables in the Environment Variables dialog box.

A.1.1.1.2 The path environment variable on Unix

Supposing that the bin directory is located at /usr/mike/j2sdk1.4.1_01/bin on a Unix system, you could temporarily set the path environment variable at a bash shell prompt with this line:

path="/usr/mike/j2sdk1.4.1_01/bin:$PATH"

This command adds the path /usr/mike/java/j2sdk1.4.1_01/bin, which contains the executable file javac.exe, to your current path variable, represented by the substitution variable $PATH.

You could also add this command line to your /etc/profile or ~/.profile file, so that the new path is set each time you boot your computer.

A.1.1.2 Running the Java compiler

With the bin directory in the path variable, you are ready to put its content to use. Type the following at a command prompt or shell:

javac

If the path is working right, it will return advice that looks somewhat like this:

Usage: javac <options> <source files> where possible options include:   -g                        Generate all debugging info   -g:none                   Generate no debugging info   -g:{lines,vars,source}    Generate only some debugging info   -O                        Optimize; may hinder debugging or enlarge class file   -nowarn                   Generate no warnings   -verbose                  Output messages about what the compiler is doing   -deprecation              Output source locations where deprecated APIs are used   -classpath <path>         Specify where to find user class files   -sourcepath <path>        Specify where to find input source files   -bootclasspath <path>     Override location of bootstrap class files   -extdirs <dirs>           Override location of installed extensions   -d <directory>            Specify where to place generated class files   -encoding <encoding>      Specify character encoding used by source files   -source <release>         Provide source compatibility with specified release   -target <release>         Generate class files for specific VM version   -help                     Print a synopsis of standard options

A.1.2 Using the Classpath

When dealing with Java, you also have to deal with the classpath. The classpath is the path that enables a Java interpreter to see the classes that it is trying to execute. When running Java from the command line, Java classes can be included using the -cp or -classpath command-line options.

For example, you could place the jar file saxon7.jar in the classpath with something like this:

java -cp c:\lib\saxon7.jar net.sf.saxon.Transform test.xml test.xsl

You can also place a JAR file in the classpath using this command on Windows:

set CLASSPATH=".;c:\lib\saxon7.jar;%CLASSPATH%"

The dot (.) refers to the current directory (the Java interpreter needs to be told explicitly to look in the current directory for classes). %CLASSPATH% adds the current classpath to the new value of CLASSPATH.

Or type something like this command on Unix:

classpath="/usr/lib/saxon7.jar:$CLASSPATH"

Another convenient way to handle the classpath is to place a copy of the desired JAR file in the jre/lib directory where your JRE is installed. For example, if your JRE is installed under C:\j2sdk1.4.1_01, it will have the subdirectory jre/lib, which holds various resources.

A.1.2.1 The jar method

If you use the -jar option, however, you can just use a regular path or the path environment variable to find a JAR file. For example, if the JAR file were in the current directory, you could simply type:

java -jar saxon7.jar

Or, if it were in C:\Temp, you could use:

java -jar c:\lib\saxon7.jar

This assumes that the manifest file in the JAR has a Main-Class field that tells the Java interpreter where the class holding the main( ) method is. For more information on running JAR-package software, see http://java.sun.com/docs/books/tutorial/jar/basics/run.html.

If you would like more help understanding how the Java classpath works and how Java finds classes to run, see http://java.sun.com/j2se/1.4.1/docs/tooldocs/findingclasses.html. For help setting the classpath for Windows, see http://java.sun.com/j2se/1.4.1/docs/tooldocs/windows/classpath.html; for help setting the classpath for Solaris or a similar Unix system, see http://java.sun.com/j2se/1.4.1/docs/tooldocs/solaris/classpath.html.

A.1.3 Installing and Running Instant Saxon

Saxon is a free, open source XSLT processor created and maintained by Michael Kay and hosted at http://saxon.sourceforge.net. Instant Saxon is a Windows 32 executable version of Saxon, that is, in essence, a parcel of Java classes packaged together in an .exe file. The last release of Instant Saxon at this writing was Version 6.5.3 (August 2003).

Michael Kay's Saxon, including Instant Saxon, was the first compliant XSLT 1.0 processor and was released 17 days after the XSLT and XPath recommendations were published in late 1999. Michael Kay is the current editor of the XSLT 2.0 specification, and he's one of the editors of XPath 2.0. Both programs are under development at the W3C. (Blessedly, he was also a technical editor for this book.)

You can find the archive for Instant Saxon 6.5.3 in examples/ch07, or you can use the directions for downloading the archive that follow.

A.1.3.1 Downloading Instant Saxon

Follow these steps (they may vary over time):

Using a web browser, go to http://saxon.sourceforge.net.
Search for InstantSaxon 6.5.3 and, after finding it, click on Download just below.
Select a mirror download server, then save the zip file instant-saxon6_5_3.zip to the directory of your choice.
When the download is complete, unzip the instant-saxon6_5_3.zip. Two files are extracted, namely, instant.html and saxon.exe.
The installation is complete.
You can use saxon.exe by copying it to your current directory, copying it to another location that is already in the path (such as C:\Windows or C:\WINNT), or adding its location to the path environment variable (see Section A.1.1.1 earlier in this appendix).

A.1.3.2 Running Instant Saxon

Display usage information for Instant Saxon by entering the following at a Windows command prompt:

saxon

Without any parameters, you should see this usage synopsis:

No source file name SAXON 6.5.3 from Michael Kay Usage: saxon [options] source-doc style-doc {param=value}... Options:   -a              Use xml-stylesheet PI, not style-doc argument   -ds             Use standard tree data structure   -dt             Use tinytree data structure (default)   -o filename     Send output to named file or directory   -m classname    Use specified Emitter class for xsl:message output   -r classname    Use specified URIResolver class   -t              Display version and timing information   -T              Set standard TraceListener   -TL classname   Set a specific TraceListener   -u              Names are URLs not filenames   -w0             Recover silently from recoverable errors   -w1             Report recoverable errors and continue (default)   -w2             Treat recoverable errors as fatal   -x classname    Use specified SAX parser for source file   -y classname    Use specified SAX parser for stylesheet   -?              Display this message

Normally, Instant Saxon expects at least two parameters: the name of the source document followed by the name of the stylesheet. Supply the names of the document and stylesheet discussed earlier on the command line, like this:

saxon test.xml test.xsl

Any file named test, regardless of the file suffix, is fictitious and used only as an example in this appendix.

To direct Instant Saxon's output to a file, use the -o option:

saxon -o test.out test.xml test.xsl

To use an XML document that contains an XML stylesheet PI, use the -a option, followed by the filename:

saxon -a test.xml

The XML stylesheet PI contains a reference to a stylesheet and will look something like:

<?xml-stylesheet href="test.xsl" type="text/xsl"?>

For version and timing information, try the -t option:

saxon -t test.xml test.xsl

If the source document has an associated DTD, you can validate it at runtime with the -v option:

saxon -v test.xml test.xsl

A DTD will be associated with the XML document by a document type declaration, which will look something like:

<!DOCTYPE test SYSTEM "test.dtd">

A.1.4 Installing and Running Saxon (Full Java Version)

Saxon is a free, open source XSLT processor that, like Instant Saxon, was created by Michael Kay and hosted at http://saxon.sourceforge.net. The recommended version of Saxon for XSLT 1.0 is Version 6.5.3. The latest version at the time of this writing is 7.7, which partially supports the working drafts for XSLT 2.0 and XPath 2.0. By the time you read this, Saxon may have gone beyond Version 7.7.

You can find the archive for Saxon 7.7 in examples/ch16, or you can get the latest version by using the directions for downloading the archive that follow.

A.1.4.1 Downloading Saxon

To download Saxon, follow these steps (which may vary over time):

Using a web browser, go to http://saxon.sourceforge.net.
Search for Saxon7.7 or later and, after finding it, click on Download just below.
Select a mirror download server, then save the zip file saxon7-7.zip to the directory of your choice.
When the download is complete, unzip the saxon7-7.zip. Many files will be extracted, including saxon7.jar.
The installation is complete.

You can use the full Java version of Saxon on any platform that supports Java, including Windows or a Unix environment such as Linux, Solaris, or Mac OS X. This requires that you have at least a JRE or JVM installed for Version 1.4 or higher. If you don't have Java on your system, you can download an SDK or JRE from http://sun.java.com. You will find installation instructions earlier in this appendix in , Section A.1.1.

A.1.4.2 Running Saxon

You can download Saxon from http://saxon.sourceforge.net, or copy the file saxon7.jar from C:\LearningXSLT\examples\ch16 (Version 7.7 of saxon7.jar exists in examples/ch16, but you may want a more recent version, if one is available). Placing the JAR file in your working directory obviates the need to deal with the classpath (see Section A.1.2, earlier in this appendix).

This file contains the Java class files that will enable you to transform documents using Saxon. Assuming that saxon7.jar is in your current directory, you can enter the line:

java -jar saxon7.jar

This should yield the following output if you used no arguments:

No source file name SAXON 7.7 from Michael Kay Usage:  java net.sf.saxon.Transform [options] source-doc style-doc {param=value}... Options:   -a              Use xml-stylesheet PI, not style-doc argument   -ds             Use standard tree data structure   -dt             Use tinytree data structure (default)   -im modename    Start transformation in specified mode   -o filename     Send output to named file or directory   -m classname    Use specified Emitter class for xsl:message output   -r classname    Use specified URIResolver class   -t              Display version and timing information   -T              Set standard TraceListener   -TJ             Trace calls to external Java functions   -TL classname   Set a specific TraceListener   -u              Names are URLs not filenames   -v              Validate source document   -w0             Recover silently from recoverable errors   -w1             Report recoverable errors and continue (default)   -w2             Treat recoverable errors as fatal   -x classname    Use specified SAX parser for source file   -y classname    Use specified SAX parser for stylesheet   -?              Display this message   param=value     Set stylesheet parameter   !option=value   Set serialization option

You can use saxon7.jar with the same arguments as you did with Instant Saxon. For example, to transform test.xml with test.xsl, type the following:

java -jar saxon7.jar test.xml test.xsl

To send output to a file, use the -o option:

java -jar saxon7.jar -o test.out test.xml test.xsl

If a document contains an XML stylesheet PI, you can use the -a option:

java -jar saxon7.jar -a test.xml

The XML stylesheet PI contains a reference to a stylesheet and will look something like:

<?xml-stylesheet href="test.xsl" type="text/xsl"?>

For version and timing information, use the -t option:

java -jar saxon7.jar -t test.xml test.xsl

If the source document has an associated DTD, you can validate it at runtime with the -v option:

java -jar saxon7.jar -v test.xml test.xsl

A DTD will be associated with the XML document by a document type declaration, which will look something like this:

<!DOCTYPE test SYSTEM "test.dtd">

A.1.4.3 Using a Windows batch file with Saxon

You can use a batch file on Windows to run Saxon's full Java version. You can copy the following lines and place them in a batch file named sp.bat:

@echo off java -jar "C:\LearningXSLT\examples\ch16\saxon7.jar" %1 %2 %3 %4 %5 %6 %7 %8 %9

This assumes that you have set up the directory C:\LearningXSLT\examples\ch16 (among other directories) for the example files. You can change the location of saxon7.jar in the batch file to match your own directory structure. If you are working on Windows 2000 Professional or XP Professional, you can delete the replaceable parameters %1 thorough %9 and use %* in their place. You could then run Saxon by typing:

sp test.xml test.xsl

A.1.4.4 Using a Unix shell script with Saxon

If you're on a Unix system, you could copy the following into a file named sp.sh:

#! /bin/sh java -jar ~/learningxslt/examples/saxon/saxon.jar $*

This script assumes that you have set up a directory called learningxslt in your home directory (something like /usr/mike, which is represented by ~/). You can change the location of saxon7.jar in the batch file to match your own set up. You could then run Saxon by typing:

sp.sh test.xml test.xsl

A.1.5 Installing and Running MSXSL

MSXSL is Microsoft's free command-line XSLT processor, available at http://msdn.microsoft.com/downloads/. MSXSL is a Windows 32 executable that requires MSXML 4.0 (msxml4.dll). This processor is incredibly small (25 KB) and is one of the fastest around, probably because it is compiled natively on Windows and uses the XSLT library included in MSXML. You can also download the source code.

By default, MSXSL uses UTF-16 output. You have to use the encoding attribute on an output element in a stylesheet to override this, which you probably will want to do because UTF-16 doesn't always produce very attractive output in a command window.

A.1.5.1 Downloading MSXSL

Follow these steps (they may vary over time):

Using a browser, go to http://msdn.microsoft.com/downloads/.
Under Searchfor Developer Downloads, search for MSXSL.
Click on the link provided to MSXSL.
The DLL msxml4.dll must also be installed for MSXSL to run. If it isn't installed, follow the link provided to the MSDN Online XML Developer Center, then download and install it according to the instructions provided.
Find the link for msxsl.exe and click it.
Save msxsl.exe to a directory of your choice.
The installation is complete.
You can use msxsl.exe by copying it to your current directory, copying it to another location that is already in the path (such as C:\Windows or C:\WINNT), or adding its location to the path environment variable (see Section A.1.1.1 earlier in this appendix).

A.1.5.2 Running MSXSL

To see the display usage information for MSXSL, enter the following at a Windows command prompt:

msxsl -?

With the -? option, you will see this usage information:

Microsoft (R) XSLT Processor Version 4.0    Usage: MSXSL source stylesheet [options] [param=value...] [xmlns:prefix=uri...]    Options:     -?            Show this message     -o filename   Write output to named file     -m startMode  Start the transform in this mode     -xw           Strip non-significant whitespace from source and stylesheet     -xe           Do not resolve external definitions during parse phase     -v            Validate documents during parse phase     -t            Show load and transformation timings     -pi           Get stylesheet URL from xml-stylesheet PI in source document     -u version    Use a specific version of MSXML: '2.6', '3.0', '4.0'     -             Dash used as source argument loads XML from stdin     -             Dash used as stylesheet argument loads XSL from stdin

MSXSL takes at least two arguments: the name of the XML source document followed by the name of the stylesheet. On the command line, type:

msxsl test.xml test.xsl

To direct output to a file, use the -o option:

msxsl -o test.out test.xml test.xsl

To transform an XML document that contains an XML stylesheet PI, use the -pi option, followed by an appropriate filename:

msxsl -pi test.xml

The XML stylesheet PI contains a reference to a stylesheet and will look something like:

<?xml-stylesheet href="test.xsl" type="text/xsl"?>

For timings, try the -t option:

msxsl -t test.xml test.xsl

If the source document has a DTD, you can validate it with the -v option:

msxsl -v test.xml test.xsl

A DTD will be associated with the XML document by a document type declaration, which will look something like:

<!DOCTYPE test SYSTEM "test.dtd">

A.1.6 Installing and Running Xalan C++

Xalan C++ is an open source XSLT processor hosted by Apache. To run, Xalan C++ also requires the C++ version of Apache's XML parser Xerces. Both Xerces C++ and Xalan C++ are available for download from the Apache site (http://xml.apache.org).

A.1.6.1 Downloading and installing Xalan C++

Follow these steps (which may vary over time) to install Xalan C++:

Using a web browser, go to http://xml.apache.org/dist/xerces-c/stable/.
Select the latest distribution archive for your platform, such as the recent versions xerces-c2_2_0-win32.zip or xerces-c2_2_0-linux8.0gcc32.tar.gz.
Save the archive to the directory of your choice.
After the download is complete, extract the files from the archive using either the unzip or tar utility.
The directory xerces-c2_2_0 is extracted to the current directory or another directory of your choice. All files from Xerces are stored under this directory.
The installation of Xerces C++ is complete. Now you must also install Xalan C++.
Using a browser, go to http://xml.apache.org/dist/xalan-c/stable/.
Select the latest distribution archive for your platform, such as Xalan-C_1_5-win32.zip or Xalan-C_1_5-linux7.2Proton.tar.gz.
Save the archive to the directory of your choice.
After the download is complete, extract the files from the archive using either the unzip or tar utility.
The directory xml-xalan is extracted to the current directory or another directory of your choice. All files from Xalan C++ are stored under this directory.
The installation of Xalan C++ is complete.

To use xalan.exe, you need to add its location to the path, as well as to the location of the Xerces bin directory. If you are working on Windows, follow the instructions in Section A.1.6.2. If you are working on a Unix platform, see Section A.1.6.3.

A.1.6.2 Setting the path variable for Xalan on Windows

If, for example, you installed (actually unzipped) the Xalan C++ archive in the root directory on Windows (C:\), the location for xalan.exe would be something like C:\xml-xalan\c\Build\Win32\VC6\Release. So in order to add this to the path, you could enter the following line:

path %path%;"C:\xml-xalan\c\Build\Win32\VC6\Release"

This command appends the path C:\xml-xalan\c\Build\Win32\VC6\Release, which contains the executable file xalan.exe, to your current path variable, represented by the substitution variable %path%. If you want, you could add this command line to your autoexec.bat file, so that the new path is set each time you boot your computer.

The C++ version of Xerces must also be in the path. If you unzipped Xerces in the root directory, the location for the Xerces dynamic-link libraries would be at C:\xerces-c2_2_0-win32\bin. Add this location to your path as you did with Xalan.

A.1.6.3 Setting the path variable for Xalan on a Unix platform

If you installed or unzipped the Xalan C++ in your home directory on a Unix platform (such as in /usr/mike), the location for xalan.exe would be something like /usr/mike/xml-xalan/c/Build/Win32/VC6/Release. To add this location to the path, enter the following line:

path="/usr/mike/xml-xalan/c/Build/Win32/VC6/Release:$PATH"

This command adds /usr/mike/xml-xalan/c/Build/Win32/VC6/Release, which contains the executable file xalan.exe, to your current path variable. (The path variable is represented by $PATH.) If you want, you could add this command line to your /etc/profile or ~/.profile file, so that the new path is set each time you boot your computer.

Xerces must also be in the path in order for Xalan to work. If you unzipped Xerces in your home directory on Unix, the location for the Xerces dynamic-link libraries would be at something like /usr/mike/xerces-c2_2_0-win32/bin. Add this location to your path as you did Xalan, and you'll be ready to run.

A.1.6.4 Running Xalan C++

With Xalan C++ and Xerces C++ installed and the proper directories in the path, you can begin using Xalan. To start, just type the name of the program on a command line:

xalan

If Xalan works, you will see the following usage information on the screen:

Xalan version 1.5.0 Xerces version 2.2.0 Usage: Xalan [options] source stylesheet Options:   -a                    Use xml-stylesheet PI, not the 'stylesheet' argument   -e encoding           Force the specified encoding for the output.   -i integer            Indent the specified amount.   -m                    Omit the META tag in HTML output.   -o filename           Write output to the specified file.   -p name expression    Sets a stylesheet parameter.   -u                    Disable escaping of URLs in HTML output.   -v                    Validates source documents.   -?                    Display this message.   -                     A dash as the 'source' argument reads from stdin.   -                     A dash as the 'stylesheet' argument reads from stdin.                         ('-' cannot be used for both arguments.)

Xalan takes at least two parameters: the name of the source document followed by the name of the stylesheet, like this:

xalan test.xml test.xsl

To direct Xalan's output to a file, use the -o option:

xalan -o test.out test.xml test.xsl

Use an XML document that contains an XML stylesheet PI, and then use the -a option, followed by the filename:

xalan -a test.xml

The XML stylesheet PI contains a reference to a stylesheet and will look something like:

<?xml-stylesheet href="test.xsl" type="text/xsl"?>

To set the number of spaces used for the indentation of output, use the -i option, followed by an integer (2 means the output will be indented by two spaces for each element level of the XML document):

xalan -i 2 test.xml test.xsl

If the source document has an associated DTD, you can validate it at runtime with the -v option:

xalan -v test.xml test.xsl

A DTD will be associated with the XML document by a document type declaration, which will look something like:

<!DOCTYPE test SYSTEM "test.dtd">