http://norman.walsh.name/2008/01/01/docbookStylesheets 11 001 2008-01-01T13:58:21-05:00 $Date$ Norman Walsh 2007 Norman Walsh The XSLT 2.0 stylesheets for DocBook are broken. They have been for a while, but I think maybe I've figured out how to fix them. There's a pervasive complexity in the XSLT 1.0 stylesheets. It's not a bad or unnecessary complexity; it's caused, at least in part, by the fact that there's a lot of flexibility in DocBook. A small example: when a chapter is formatted, the chapter will have a title and might have a subtitle (among other things); these elements each individually might or might not be inside an info element. For some elements, like bibliography, the situation is even more complicated because the title is optional (if not present, a locale-specific default title must be used). In designing the XSLT 2.0 stylesheets for DocBook, I wanted to factor out some of this complexity. The result is a multi-phase transformation: The first phase adds an xml:base attribute to the root element so that URI resolution in subsequent phases will know the correct base URI. It resolves entityref attributes into fileref attributes because subsequent phases won't have access to the entity declarations in the original document. If the root element does not declare the DocBook namespace, it moves all elements in no namespace into the DocBook namespace. This allows the XSLT 2.0 stylesheets to format DocBook V4.x documents; in fact, not only are the elements moved into the DocBook namespace, but they're transformed a bit too, so that they (are more likely to) conform to DocBook V5.x. This is a convenience, the XSLT 2.0 stylesheets aren't guaranteed to format DocBook V4.x correctly. The second phase applies profiling. The third phase normalizes markup. This is the phase that reduces the complexity described above: info elements are added uniformly (so all elements that can be inside or outside of an info are always inside), defaulted titles are made explicit, and a number of other changes are made to make the markup more regular. The problem with this approach is that it interferes with users' expectations. Not stylesheet users per se, but stylesheet customizers. If a customizer wants to change the root template (to tinker with the HTML page metadata, for example), he or she is naturally going to add a new root template to their customization layer: <xsl:template match="/"> … </xsl:template> Trouble is, in this multi-phase approach, that just completely breaks everything. The root template expects to run the phases, and if you steal that, it just goes pear shaped. What you have to do instead is add this template to your customization layer: <xsl:template match="*" mode="m:root"> … </xsl:template> Now, I suppose, in the grand scheme of things that's not so bad, but it's ugly. My first approach to fixing this problem was to break the DocBook stylesheet into explicit, discrete phases. Unfortunately, this requires the user to actually setup a pipeline and run a series of separate transformations. In a post-XProc world, this might actually be ok, but today, it's setting the bar awfully high for your average user. So I have a new approach. Instead of using the root template to run the phases, I use a named template. One of the features of XSLT 2.0 is that you can start a transformation with a named template. Using this approach, you must tell the processor to start with the right template (using -it:format-docbook in the Saxon command-line case), but otherwise, you're free to customize the “/” template to your hearts content. But you're hosed if you forget to start at the right named template. To detect this error, the format-docbook template injects a harmless processing instruction before the document element so that subsequent processing can determine if the user forgot to use the named template. In the short and medium term, I think this is the right approach. In the long term, XProc will rule the world and we can simplify things further with a series of explicit transformations. I've got this implemented in the “xsl2-namedt” branch of the repository. If no one tells me why this approach is either stupid or insane, or both, I'll probably move it to the trunk in a couple of weeks.