Once you have your catalog file, you have to tell the processor to use it. How you do that depends on which processor you are using.
All of the Java XSL processors can use the Java resolver classes
written by Norm Walsh and made available through the Apache XML
Project. Download the latest version of
resolver.jar from http://xml.apache.org/commons/dist/ (it may have a version number in the name) and copy it to a convenient location. The
resolver.jar file is also included in distribution of the Xerces parser starting with version 2.6.2.
To use the resolver, you add the file's pathname to your
CLASSPATH environment variable, create a
CatalogManager.properties file, and add several resolver
options to your command line as described below.
resolver.jar file from http://xml.apache.org/commons/dist/ (it may have a version number in the filename).
Add the pathname of the
resolver.jar file to your CLASSPATH. See the section “Installing Saxon” for information on setting CLASSPATH.
Create a file named
CatalogManager.properties, as described below.
Add the directory containing the
CatalogManager.properties file to your CLASSPATH.
CatalogManager.properties file tells the resolver where to look for catalog files and sets configuration options. That file is placed in a directory that is included in your Java CLASSPATH. The content of the file looks something like the following:
catalogs=catalog.xml;../../dtd/docbook45/docbook.cat relative-catalogs=false static-catalog=yes catalog-class-name=org.apache.xml.resolver.Resolver verbosity=1
The first line is the most important, as it indicates the pathnames of catalog files to use, in a semicolon-separated list. The filenames can be absolute paths, or relative to the
CatalogManager.properties file. If you want relative pathnames to be interpreted relative to your document's location, then set
relative-catalogs=true. In this example, the path
../../dtd/docbook45/docbook.cat is taken to be relative to the directory containing the
CatalogManager.properties file. The list of catalogs can include SGML catalogs, such as that included with the DocBook XML DTD.
A Saxon command line that uses the catalog resolver looks like the following:
For Saxon: java -cp "/usr/java/saxon.jar:/docbook-xsl/extensions/saxon653.jar:\ /usr/share/resolver.jar;/usr/share" \ com.icl.saxon.StyleSheet \ -x org.apache.xml.resolver.tools.ResolvingXMLReader \ -y org.apache.xml.resolver.tools.ResolvingXMLReader \ -r org.apache.xml.resolver.tools.CatalogResolver \ -u \ -o myfile.html \ myfile.xml docbook.xsl
In this example, the
CatalogManager.properties files are placed in
/usr/share. The example includes the
-cp Java command option to temporarily add to the CLASSPATH for that command. If you instead add them to your CLASSPATH environment variable, you do not need that option in each command. The
-u Saxon option tells Saxon to treat pathnames specified on the command line as URIs, so that the catalog can use URI lookups. The
-r options configure Saxon to use the resolver code.
Resolving short references like
docbook.xsl on the command line requires Java version 1.4 or later. If you are using Java version 1.3 or earlier, the name must use URI syntax such as
file:///docbook.xsl. Such URIs are mapped to the real location by the catalog.
XML catalogs do not work with Xalan 2.4 1 in Java 1.4. See the section “Bypassing the old Xalan installed with Java” for information on updating your Xalan on Java 1.4.
To use catalogs with Xalan, you must first set up the
CatalogManager.properties files as described in the section “Using catalogs with Saxon”. Then you can use a command line such as:
For Xalan: java -cp "/usr/java/xerces.jar:/usr/java/xalan.jar:\ /docbook-xsl/extensions/xalan25.jar:\ /usr/share/resolver.jar:/usr/share" \ org.apache.xalan.xslt.Process \ -ENTITYRESOLVER org.apache.xml.resolver.tools.CatalogResolver \ -URIRESOLVER org.apache.xml.resolver.tools.CatalogResolver \ -out myfile.html \ -in myfile.xml \ -xsl http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl
The current version of Xalan (2.7.0) does not resolve URIs from the command line using the catalog file. However, if the same URI is used in a stylesheet processing instruction inside the document (instead of using the
-xsl option), then the catalog is consulted and the URI remapped.
As with the Saxon example, the
CatalogManager.properties files are assumed to be located in
/usr/share, but you can locate them wherever it is convenient.
The xsltproc processor is not Java based so it uses its own mechanism for catalogs. It does not use
CatalogManager.properties. By default, xsltproc looks for an XML catalog file named
/etc/xml/catalog (except on Windows, for which there is no default location). You can specify a different file by setting an
XML_CATALOG_FILES environment variable. It should contain URIs to one or more catalog files. A local URL can be a relative pathname such as
catalog.xml in the current directory, or an absolute pathname if it uses the
file:///path/to/file URI syntax (even on Windows). If you have more than one catalog file, then separate the URIs with spaces in the environment variable. (Earlier versions of xsltproc supported only one catalog file.) The
variable is optional and turns on catalog debugging if its value is nonzero.
The following is an example of their usage.
For xsltproc: XML_CATALOG_FILES="catalog.xml file:///usr/share/xml/catalog.xml" \ XML_DEBUG_CATALOG=1 \ xsltproc docbook.xsl myfile.xml
This example set the environment variables on for this command. Normally you would set the environment variables using the regular mechanism for your operating system so you do not have to add them to every command.
Alternately, you can name your catalog file with the default pathname
/etc/xml/catalog, and xsltproc will just use it (except on Windows).
The catalog processing mechanism in xsltproc will properly handle short references such as
fo/docbook.xsl for the stylesheet name on the command line.
|DocBook XSL: The Complete Guide - 4th Edition||PDF version available|
Copyright © 2002-2007 Sagehill Enterprises