Chapter 2. Generating the XML catalog

As of this document, the DocBook stylesheets cannot created "chunked" (that is, one document split into several separate pages) XHTML output that passes the validators. In particular, the files are missing a !DOCTYPE declaration. In addition, I wanted to make some small modifications to the visual rendering.

The DocBook way to do this is to use custom stylesheets - these are essentially XSLT source files that include the system's DocBook stylesheets, and add the necessary modifications. The layout of the doc/ directory containing the DocBook source was as follows :

 
	doc/
		Makefile.am
		source.xml
		xsl/
			xhtml.xsl
			xhtml-chunk.xsl
			xhtml-common.xsl

Note that xhtml.xsl and xhtml-chunk.xsl both include (xsl:import) xhtml-common.xsl. This leaves us with two issues with respect to the GNU autotools: first, locating the custom stylesheets, and second, locating the system stylesheets. We do both via an XML catalog file. A catalog file is used for locating documents via URIs. To make this work with autoconf, we make it an input file (that is, create a file catalog.xml.in in the xsl/ directory and list it in AC_OUTPUT in configure.in as usual). Our doc/xsl/catalog.xml.in looks like this :

<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
        "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
        <nextCatalog catalog="@XML_CATALOG@" />

        @CAT_ENTRY_START@
        <uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"
                uri="@DOCBOOK_ROOT@/xhtml/docbook.xsl"/>
        <uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"
                uri="@DOCBOOK_ROOT@/xhtml/chunk.xsl"/>
        @CAT_ENTRY_END@

        <uri name="xsl/xhtml-common.xsl" uri="@top_srcdir@/doc/xsl/xhtml-common.xsl"/>
</catalog>

There are three things to note here. First, that we try and find the system's XML catalog, which, if it exists, should contain the local file URIs for the DocBook stylesheets; this means that, when we refer to the docbook.xsl URI, we will get the local file version instead of going over the net to request it. This nextCatalog declaration silently fails if the file does not exist, so that's OK.

Second, we have explicit declarations for the two DocBook stylesheets I want to use. @DOCBOOK_ROOT@ is the directory location of the XSL stylesheets, if we could find them. If the catalog file was found, then this section is commented out via the CAT_ENTRY being set to XML comment delimiters - we do not want to over-ride a value set in a system catalog.

Finally, we have a catalog entry for the custom xhtml-common.xsl stylesheet, which is included by the others as mentioned above. This is necessary to build correctly when building in a different directory than the source directory - the .xsl files will be in the ${top_srcdir}/doc/xsl/, but the current directory will not be $top_srcdir}/doc.