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.

path %path%;c:Javaj2sdk1.4.1_01in

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

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

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:libsaxon7.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.

Follow these steps (they may vary over time):

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">

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

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.

You can download Saxon from http://saxon.sourceforge.net, or copy the file saxon7.jar from C:LearningXSLTexamplesch16 (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">

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:LearningXSLTexamplesch16saxon7.jar" %1 %2 %3 %4 %5 %6 %7 %8 %9

This assumes that you have set up the directory C:LearningXSLTexamplesch16 (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

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

Follow these steps (they may vary over time):

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">

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

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.

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-xalancBuildWin32VC6Release. So in order to add this to the path, you could enter the following line:

path %path%;"C:xml-xalancBuildWin32VC6Release"

This command appends the path C:xml-xalancBuildWin32VC6Release, 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-win32in. Add this location to your path as you did with Xalan.

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. With xalan.exe in the path variable, you are ready to put it to use.

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.

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">

One option is to copy the JAR file jdxslt.jar from the lib directory of the archive to one of the chapter directories under C:LearningXSLTexamples directory. Placing the JAR in a working directory obviates the need to deal with the Java classpath (see Section A.1.2, earlier in this appendix).

Test to see if jd.xslt works by typing the following line at a command prompt:

java -jar jdxslt.jar

This should give you:

jd.xslt processor version 1.5.2
  
Usage: java jd.xml.xslt.Stylesheet [options] xml [xsl...]
  
xml                   the uri of an input xml document, "-" for STDIN
xsl...                zero or more uris of stylesheets - if their number is
                      = 0: use the associated stylesheets of the xml document
                      = 1: transform the input with that stylesheet
                      > 1: chain the transformations
                      the uri "urn:jdxslt:identity" denotes the identity
                      transformation
options:
-entityresolver <cls> set a sax EntityResolver
-errorstack           show the java call stack in case of an error
-media <media>        filter associated stylesheets by their media attribute
-msglistener <class>  set a message listener
-out <file>           write the output to the file (default is System.out)
-out:<prop> <value>   set the value of a xsl:output property
-param <name> <expr>  set the value of a toplevel parameter (expr is a context-
                      free XPath expression). Multiple parameters are allowed
-parser <class>       set a sax parser
-parserxml <class>    set a sax parser for input xml documents
-parserxsl <class>    set a sax parser for the stylesheet
-proxy <url>          set a proxy host
-repeat <number>      repeat the transformation n times
-security <class>     set a XsltSecurityManager
-title <title>        filter associated stylesheets by their title attribute
-trace                create trace output
-uriresolver <class>  set a UriResolver
-validate             validate xml documents
-verbose              turn on verbose mode to display transformation info
-w0                   recover silently from recoverable errors
-w1                   report recoverable errors and continue (default)
-w2                   treat recoverable errors as fatal
java -jar saxon7.jar test.xml test.xsl

To transform a file, use the following:

java -jar jdxslt.jar test.xml test.xsl

To transform a source file with more than one stylesheet, use the following line:

java -jar jdxslt.jar test.xml test1.xsl test2.xsl test3.xsl

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

java -jar jdxslt.jar -out test.out test.xml test.xsl

Set an output property (based on the attributes of the output element) using the -out: option:

java -jar jdxslt.jar -out:indent yes test.xml

For verbose output, use the -verbose option:

java -jar jdxlst.jar -verbose test.xml test.xsl

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

java -jar jdxslt.jar -validate 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">