Table of Contents
Some time ago the Oasis group developed a means of resolving requests for files and resolving them in a different way. Of interest to Website is the idea of trying to pick a file from the internet and 'diverting' that call to resolve the request using a file on disk. That is the basis of the catalog mechanism. DocBook XSL: The Complete Guide describes this in some detail, Norm Walsh writes about it with respect to Docbook.
For some time now, the main Docbook distribution has held a
file named catalog.xml. If you look at it,
you'll find this idea of 'remapping' items to a local disk
copy.
Similarly, in the main Docbook xsl stylesheets there is
similarly a file called catalog.xml. Again this
maps the web based copies of the latest stylesheets and 'remaps'
them to local copies.
Finally and not surprisingly, the Website distribution also
contains a catalog.xml file. This maps the
schemas by their long names, to the directories containing those
files.
This document will (eventually) contain a more detailed write-up on catalog usage. Suffice it to say that for the time being, the catalogs provided can be used to resolve or remap these external, web based entities to local files.
The starting point is to tell the xml parser that is should
use a catalog resolver. In the provided
build.xml file, the point at which the xslt
engine is called up, is by means of the parameters to the xslt
engine. The parameter -x
org.apache.xml.resolver.tools.ResolvingXMLReader does this. A
minor mystery is solved when someone tells you that the resolver
software goes hunting for a file called
catalogManager.properties, which is used to
start the hunt for resolution of entities. An example file is shown below
Example 17. An example catalogManager.properties file
#Controls the operation of the xml catalog manager #CatalogManager.properties verbosity=1relative-catalogs=yes # Always use semicolons in this list catalogs=/sgml/catalog.xml
prefer=public static-catalog=yes
allow-oasis-xml-catalog-pi=yes
| Set this to a higher number to get more information about resolving detail. Not too high though! Perhaps 3 maximum |
| This is where to find the first catalog file |
| For this level of detail, you can look up the standard in Appendix A |
an example catalog file is shown in Example 18
Example 18. An example catalog.xml for Oasis catalogs
<?xml version="1.0" ?> <catalog prefer="public" xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> <group xml:base="file:///sgml/docbook"></group> </catalog>
| Where to start resolution, for relative paths |
| Main Docbook catalog |
| Next, use the Website catalog |
| Finally, look in the Docbook xsl catalog |
Perhaps now you can see how firstly the properties file is read, and points to the first catalog. That, in turn points out the catalogs (as delivered by the Docbook team) which can be updated to the most recent version. Each catalog then 'maps' from one actual web based location through to a local, disk based file. That's the end product!
If you need to modify these, work through them one at a time and see where you are going wrong. By increasing the resolver output (the 'verbosity' setting above), you will be able to see what is happening if you need to debug it.