Chapter 5. XML catalogs

Table of Contents

Why use XML catalogs
How to write an XML catalog file
Resolve the DTD location
Locate an XSL stylesheet
Map a web address to a local file
Map many references with rewrite entries
Using multiple catalog files
Example DocBook catalog file
How to use a catalog file
Using catalogs with Saxon
Using catalogs with Xalan
Using catalogs with xsltproc

A catalog in XML provides a mapping from generic addresses to specific local directories on a given machine. A catalog can be used to locate the DocBook DTD, system entity files, and stylesheet files during processing. Catalog files add a degree of flexibility to your setup. Once you have set up your scripts and Makefiles to use catalog files, if you rearrange things or transfer to a different system, you can just edit the catalog file to remap all the old paths to new locations.

There are two kinds of catalogs that can be used with DocBook: SGML catalogs and XML catalogs. They use different syntax, and different tools may support one kind or the other. SGML catalogs are older and simpler. XML catalogs do everything that SGML catalogs do and much more. For that reason, only XML catalogs are discussed here. If you want to read the original standards documents, see XML Catalogs: Committee Specification 06 Aug 2001 for XML catalogs, or Entity Management -- OASIS Technical Resolution 9401:1997 for SGML catalogs. The web article XML Entity and URI Resolvers by Norman Walsh provides further information about both kinds of catalogs.

Why use XML catalogs

People use catalogs to make their XML setup more portable and more flexible. With catalogs, you can:

  • Use stable PUBLIC identifiers in your DOCTYPE declarations in your files, and not worry about using the SYSTEM identifier to find the DTD file or system entity files. The PUBLIC identifier can be mapped to a specific location on a given machine with a catalog. If you move your files to a new machine, you do not have to edit them all to change the SYSTEM reference, you just edit the catalog's mapping of the PUBLIC identifier.

  • Write Makefiles with generic pathnames to your stylesheet, and let the catalog remap the pathname to a location on the machine. When you move your setup and files to a different machine or to different locations, you do not have to fix internal references in your documents, stylesheets, and Makefiles. You can just use a catalog file to map the generic paths to the new locations.

  • Use stable Internet URL addresses for your DTD system identifier or stylesheet pathname, but let the catalog resolve them to pathnames on the local machine. That way you get efficient processing if they are available locally, and it falls back to network access only if it has to.

  • Select a different stylesheet for the same command by selecting a different catalog file that maps the pathname to a different location. For example, you could put docbook.xsl on all your command lines in your Makefiles, then have the Makefile map that to, say, chunk.xsl stylesheet if a variable is set.

  • Test new releases of the stylesheets or DTD by temporarily changing your catalog to point to them.