- Using a command-line utility
- Using the Xalan executable
- Using TestXSLT
- Enabling ICU support for the Xalan executable and/or testXSLT

| Using a command-line utility |

To perform a transformation, you can call Xalan-C++ from the command line (or script), or from within an application (see Usage Patterns).

To perform a transformation from the command line or a script, you can use Xalan or testXSLT. The testXSLT executable has been around since the inception of Xalan-C++ and supports a variety of options. The Xalan executable is newer, simpler to use, and supports fewer options.

To perform a transformation from the command line or a script with either executable, do the following:

1. Download Xalan-C++.
2. Set the path/library path to include the Xalan executable and the Xalan and Xerces libraries.
3. Call the executable with the appropriate flags and arguments (described below).

| Using the Xalan executable |

Call the Xalan executable as follows:
`Xalan [options] xmlSource xslStylesheet`
where xmlSource is the XML source document, xslStylesheet is the stylesheet to apply, and [options] are any (or none) of the following:

Option | Description
-a | Use stylesheet processing instruction, 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 transformation result to this file (rather than to the console).
-p name expr | Set a stylesheet parameter with this expression.
-t name expr | Diplay timing information.
-u name expr | Disable escaping of URLs in HTML output.
-v | Validate the XML source document.
- | A dash as the 'source' argument reads from stdin. A dash as the 'stylesheet' argument reads from stdin. ('-' cannot be used for both arguments.)

To display a list of the options call the Xalan executable as follows:

`Xalan -?`

| Using TestXSLT |

Call the testXSLT executable with the flags and arguments described below. The following command line, for example, includes the -IN, -XSL, and -OUT flags with their accompanying arguments -- the XML source document, the XSL stylesheet, and the output file:
`testXSLT -IN foo.xml -XSL foo.xsl -OUT foo.out`

The testXSLT executable can take the following flags and arguments (the flags are case insensitive):

    -IN inputXMLURL
    -XSL XSLTransformationURL
    -OUT outputFileName
    -H (Display list of command-line options)
    -? (Display list of command-line options)
    -V (Version info)
    -QC (Quiet Pattern Conflicts Warnings)
    -Q  (Quiet Mode)
    -INDENT (Number of spaces to indent each level in output tree --default is 0)
    -VALIDATE (Validate the XSL and XML input -- default is not to validate)
    -TT (Trace the templates as they are being called)
    -TG (Trace each result tree generation event)
    -TS (Trace each selection event)
    -TTC (Trace the template children as they are being processed)
    -XML (Use XML formatter and add XML header)
    The -XML flag must be set:
      -NH (Don't write XML header)
    -HTML (Use HTML formatter)
    The -HTML flag must be set:
      -NOINDENT (turns off HTML indenting)
    The -XML or -HTML flag must be set:
      -STRIPCDATA (Strip CDATA sections of their brackets, but do not escape)
      -ESCAPECDATA (Strip CDATA sections of their brackets, and escape)
    -TEXT (Use simple Text formatter)
    -DOM (Test for well-formed output --format to DOM then to XML for output)
    -XST (Format to Xalan source tree, then to XML for output)
    -XD (Use Xerces DOM instead of Xalan source tree)
    -DE Disable built-in extension functions)
    -EN (Specify the namespace URI for Xalan extension functions; the default
         is 'http://xml.apache.org/xslt')
    -PARAM name expression (Set a stylesheet parameter)

Use -IN to specify the XML source document.

Use -XSL to specify the XSL stylesheet file.

Use -DE not to load the standard set of extension functions.

Use -TEXT if you want the output to include only text nodes without any escaping.

Use -HTML to write 4.0 transitional HTML (some elements, such as <br>, are not well formed XML).

To set stylesheet parameters from the command line, use
`testXSLT -PARAM name expression`
To set the parameter to a string value, enclose the string in single quotes (') to make it an expression.

| Enabling ICU support for the Xalan executable and/or testXSLT |

You can set up the International Components for Unicode (ICU) to enhance the support that Xalan-C++ provides for encoding, number formatting, and sorting. For more information, see Using the ICU.

If you have built and integrated the ICU with Xerces-C++, Xalan and testXSLT (like any Xalan-C++ application) automatically uses ICU support for output encoding. See Building ICU for Xerces-C++.

The Xalan executable depends on the use of an ICU-enabled Xalan library for number formatting and sorting (see below). The testXSLT executable conditionally includes ICU support for number formatting and sorting. For testXSLT, look in process.cpp for the `#if defined(XALAN_USE_ICU)` blocks. These blocks #include the ICUBridge headers, and substitutes ICU support for xsl:number, format-number(), and xsl:sort. To activate this support:

1. Download and build the ICU (see Using the ICU).
2. Rebuild Xalan and or testXSLT with the ICU enabled (see below).

| Rebuilding Xalan and/or TestXSLT in Windows |

1. For Windows, the ICUBridge is part of the Xalan library. Build an ICU-enabled Xalan library using the AllInOneWithICU project.
2. For TestXSLT, uncomment "#define XALAN_USE_ICU" in process.cpp.
3. Build Xalan.exe and/or TestXSLT.exe.

| Rebuilding Xalan and/or testXSLT in UNIX |

In the Linux, AIX, HP-UX 11, and Solaris builds, the ICUBridge is in the core Xalan library (libxalan-c1_6.so in Linux; libxalan-c1_6.so in AIX; libxalan-c1_6.sl in HP-UX 11; libxalan-c1_6.so in Solaris ), so you must rebuild this library along with Xalan and/or testXSLT.

Before you do the build, define the XALAN_USE_ICU environment variable. For information about defining this environment variable and doing a build, see Steps for doing a UNIX build.

The make file uses the XALAN_USE_ICU environment variable to do the equivalent of a #define and to add ICUBridge to the list of dependencies for testXSLT. If you uncomment the `#define XALAN_USE_ICU` statement in process.cpp (which is the right thing to do in Windows), you will get an error in AIX ("The macro 'XALAN_USE_ICU' has already been defined"), an error in HP-UX 11 ("Redefinition of macro 'XALAN_USE_ICU' differs from previous definition"), or a warning in Linux or Solaris about duplicate settings when you run the make, and testXSLT does not link with ICUBridge.

Copyright © 2001 The Apache Software Foundation. All Rights Reserved.