Send As SMS

Wednesday, March 22, 2006

Customising docbook-xsl output

Docbook-xsl includes some reasonably presentable HTML renderings of docbook sources, but I wanted to place some additional navigation links in the header of the resulting document. The manual helpfully points out that that a series of templates called user.{header|footer}.{navigation|content} are available for this purpose, but fails to explain the need to create something called a customization layer in order to do this. The start of the HTML customisation chapter does refer to these layers, but does so in a slightly roundabout way (instead of "you need to create a layer to use the options in this chapter" it advises you to consider whether you really need one before writing one; knowing neither what nor how, I moved on). A post to the docbook-apps mailing list was answered in under an hour (wow!) by Jörg Möbius who pointed out that a customization layer was required, and even provided a sample. For future reference:
<?xml version='1.0'?>

<xsl:stylesheet xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
<xsl:import href="/usr/share/xml/docbook/stylesheet/nwalsh/html/chunk.xsl">
<xsl:template name="user.header.navigation">
<div>STUFF</div>
</xsl:template>
</xsl:stylesheet>
(The hard-coded path is reasonable for use on Debian and similar installations of docbook-xsl.)