John Levon

levon@movementarian.org

2003 John Levon This document can be freely translated and distributed. It's released under the LDP License. DocBook XML autotools autoconf automake catalog XSLT xsltproc DocBook XML is a simple standard for authoring technical documentation. I wanted to use DocBook XML as my source format for documentation for a project which used the GNU autotools. It's less than obvious; this document describes the method I used to get things working. It assumes that you are using the xsltproc program to generate output from the source XML and a number of custom XSL stylesheets. 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. We need to derive the variables mentioned in the last chapter, plus a couple more. Here is an example macro for this : AC_DEFUN(AX_CHECK_DOCBOOK, [ # It's just rude to go over the net to build XSLTPROC_FLAGS=--nonet DOCBOOK_ROOT= if test ! -f /etc/xml/catalog; then for i in /usr/share/sgml/docbook/stylesheet/xsl/nwalsh /usr/share/sgml/docbook/xsl-stylesheets/; do if test -d "$i"; then DOCBOOK_ROOT=$i fi done # Last resort - try net if test -z "$DOCBOOK_ROOT"; then XSLTPROC_FLAGS= fi else XML_CATALOG=/etc/xml/catalog CAT_ENTRY_START='<!--' CAT_ENTRY_END='-->' fi AC_CHECK_PROG(XSLTPROC,xsltproc,xsltproc,) XSLTPROC_WORKS=no if test -n "$XSLTPROC"; then AC_MSG_CHECKING([whether xsltproc works]) if test -n "$XML_CATALOG"; then DB_FILE="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" else DB_FILE="$DOCBOOK_ROOT/docbook.xsl" fi $XSLTPROC $XSLTPROC_FLAGS $DB_FILE >/dev/null 2&>&1 << END <?xml version="1.0" encoding='ISO-8859-1'?> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> <book id="test"> </book> END if test "$?" = 0; then XSLTPROC_WORKS=yes fi AC_MSG_RESULT($XSLTPROC_WORKS) fi AM_CONDITIONAL(have_xsltproc, test "$XSLTPROC_WORKS" = "yes") AC_SUBST(XML_CATALOG) AC_SUBST(XSLTPROC_FLAGS) AC_SUBST(DOCBOOK_ROOT) AC_SUBST(CAT_ENTRY_START) AC_SUBST(CAT_ENTRY_END) We define the variables we mentioned in the previous chapter. Additionally we set @XSLTPROC_FLAGS@ so that we only retrieve stylesheets over the network as a last resort. Note that this test does not check that a system that has an /etc/catalog/xml file works as expected. You may need or want to change the DocBook root directories that are searched for. The only other configure.in change you need is to add doc/xsl/catalog.xml to the AC_OUTPUT files. Here is a suitable cut-down automake input file for the setup above : XSLTPROC=xsltproc XSLTPROC_FLAGS=@XSLTPROC_FLAGS@ XHTML_STYLESHEET=$(srcdir)/xsl/xhtml.xsl CHUNK_XHTML_STYLESHEET=$(srcdir)/xsl/xhtml-chunk.xsl XML_CATALOG_FILES=xsl/catalog.xml htmldir = $(prefix)/share/doc/@PACKAGE@ dist_html_DATA = @PACKAGE@.html if have_xsltproc @PACKAGE@.html: ${top_srcdir}/doc/@PACKAGE@.xml XML_CATALOG_FILES=$(XML_CATALOG_FILES) $(XSLTPROC) $(XSLTPROC_FLAGS) -o $@ $(XHTML_STYLESHEET) $< chunk: ${top_srcdir}/doc/@PACKAGE@.xml $(XSLTPROC) $(XSLTPROC_FLAGS) $(CHUNK_XHTML_STYLESHEET) $< else chunk: @PACKAGE@.html: touch $@ endif distclean-local: $(RM) -f xsl/catalog.xml Clearly not the greatest Makefile ever, but you get the idea. The chunk target generates the chapter-per-file XHTML output. Note that we use XML_CATALOG_FILES in the environment to specify the catalog file to xsltproc. Later xsltproc versions allow you to specify more than one catalog in this variable, separated by spaces; but as it's not universal, we've used nextCatalog instead. Here's a listing of the simpler custom style sheet. Note that the system DocBook stylesheet is referred to by the URI given in the catalog files, and the common custom stylesheet is referred to directly. <?xml version='1.0'?> <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:doc="http://nwalsh.com/xsl/documentation/1.0" version="1.0"> <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"/> <xsl:import href="xhtml-common.xsl"/> <xsl:output method="xml" encoding="ISO-8859-1" indent="yes" doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN" doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd" /> </xsl:stylesheet> Much thanks to Alex Lancaster who helped explain some of this to me. A thread on the docbook-apps mailing list discussing the above problems. A description of using XML catalogs for finding stylesheets. A free book on the GNU Autotools. A free book on DocBook SGML/XML.