How to use a catalog file

How to use a catalog file
	Chapter 4. XML catalogs

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

Using catalogs with Saxon

Here is how you get catalogs working with Saxon:

Download the 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.

The 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 this:

catalogs=catalog.xml;../../dtd/docbook44/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/docbook44/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.

If the catalog setup is not working, try setting the verbosity value to a higher number, up to 4 for maximum debug information.

A Saxon command line that uses the catalog resolver looks like this:

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 resolver.jar and 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 don't 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 -x, -y, and -r options configure Saxon to use the resolver code.

Note

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.

Using catalogs with Xalan

Note

XML catalogs don't 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 resolver.jar and 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

Note

The current version of Xalan (2.6.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 resolver.jar and CatalogManager.properties files are assumed to be located in /usr/share, but you can locate them wherever it is convenient.

Using catalogs with xsltproc

The xsltproc processor is not Java based so it uses its own mechanism for catalogs. It does not use resolver.jar or 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 XML_DEBUG_CATALOG environment variable is optional and turns on catalog debugging if its value is nonzero. Here 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 don't 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.


Example DocBook catalog file		Part II. Stylesheet options