XML catalogs can make your website processing easier and faster. An XML catalog can eliminate the slow web access that Website uses by default. It can also eliminate potential errors related to not being able to find a DTD or stylesheet file. See Chapter 4, XML catalogs for more information on catalogs in general.

Some of the stylesheets that come with the Website distribution import the stock DocBook XSL stylesheets. The xsl:import elements use web URLs to fetch the DocBook stylesheets over the Internet. That way it is likely to work upon installation, since there is no way for the files in the distribution to find local copies of the files. But the DocBook XSL stylesheets are big, and downloading them each time slows down the processing considerably.

An XML catalog can be used to redirect the web references to local file locations. For example, the Website stylesheet module website-common.xsl used in all of the main stylesheets imports the stock DocBook XSL stylesheet from http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl. An XML catalog entry can redirect this to a local file location such as /usr/share/xml/docbook-xsl-1.68.1/html/docbook.xsl. This example catalog entry does it.

  <rewriteURI
    uriStartString="http://docbook.sourceforge.net/release/xsl/current/"
    rewritePrefix="file:///usr/share/xml/docbook-xsl-1.68.1/"/>

This catalog entry recognizes the first part of the URL and remaps that first part to the value of rewritePrefix. By using prefix mapping, you only need one entry to map all the stock DocBook stylesheets.

To put the catalog to use, you have to include XML catalog resolution in your processing commands. See the section “How to use a catalog file” for how to do that.

You can also use an XML catalog to locate the stylesheets and DTDs that are included with the Website distribution. This is most easily done by adding a nextCatalog entry to your XML catalog that points to the catalog distributed with Website (starting with version 2.4). For example, add this to your main catalog file:

<nextCatalog catalog="/usr/share/xml/website-2.5.1/catalog.xml" />

Adjust the path to match where you installed Website. When you process with your main catalog file, the Website catalog will also be loaded. That catalog will resolve references to Website DTDs that your files may contain. It also lets you call one of the Website stylesheets by just specifying its name, rather than the path to the file. For example, you could use a command like this:

XML_CATALOG_FILES=file:///usr/share/xml/catalog.xml \
xsltproc  --output  autolayout.xml  autolayout.xsl  layout.xml

The reference to autolayout.xsl is resolved by your main catalog branching to the Website catalog, where it finds a match on that name.