DocBook XSLT 2.0 Stylesheets released

Volume 14, Issue 32; 25 Aug 2011

Eventually, you have to ship. Announcing the first release of the DocBook XSLT 2.0 stylesheets for DocBook.

I've been using the DocBook XSLT 2.0 stylesheets almost exclusively for ages. Years, at least. Last year, Jiří Kosek worked on them as part of his Google Summer of Code project.

All-in-all, I think things are in pretty good shape. Probably less so for the FO stylesheets than the HTML stylesheets, but even so, the most significant impediment to broader use seems to be the fact that I've never released them.

Go figure.

Ok. So here's a pointer to the “0.0” release:

Feel free to ignore the “2.” in front of the version number. The real purpose of the leading numeral two is to unambiguously distinguish the version of these stylesheets from the version of the 1.0 stylesheets.

About the 1.0 stylesheets: they're still excellent, I still support them, and I don't think there's any reason to imagine that the 2.0 stylesheets will replace them anytime soon. I've just been focusing my personal energies (the tiny sliver that this project gets) on the 2.0 stylesheets.


Well, first and foremost because I think XSLT 2.0 is the future. Actually, 2.0 is the present. XSLT 3.0 is the future, but one step at a time. There's nothing wrong with XSLT 1.0, but some things are really quite hard to do in 1.0. Things that are pretty easy in 2.0. Maybe I'm just lazy.

One of the reasons that I think XSLT 2.0 is the future is the ecosystem that's growing around it. XSLT 2.0 and XQuery use the same data model. My XProc processor uses that data model. When MarkLogic decided to implement XSLT, it was XSLT 2.0 that was the obvious answer.

And finally, and possibly of equal importance, a major break is a chance to do things differently. Changes to the 1.0 stylesheets have to be taken carefully and with a serious view towards backwards compatibility. I don't know how many pages in the world go through those stylesheets, but I bet it's a honking big number. You can't just introduce radical changes to the design (or output) of those stylesheets without a lot of warning and very good cause.

Design goals

If I'm looking at the 2.0 stylesheets as a chance to do things differently, I suppose I should say a bit about what I want to do differently.

First and foremost: these are XSLT 2.0 stylesheets for DocBook V5.0. They aren't expected to produce meaningful results on XSLT 1.0 processors or on DocBook V4.x (or earlier, non-namespaced variants of DocBook).

General goals
  • Pipeline friendliness. It's quite possible that this project could eventually require an XProc processor. It doesn't yet, but I'm trying to build things in a way that decomposes into seperable pipeline steps in an obvious way. (For example, if you said you really, really needed to process DocBook V4.5 documents with these stylesheets, I'd unflinchingly suggest a two-stage pipeline where the first stage converted your 4.5 document into 5.0.)

  • User friendliness. It should be easy to use the stylesheets and they should produce results that make sense. That means providing extension functions if they're necessary, supporting ancillary document types (website and slides), developing or porting new output types, etc.

    If you've been using the 1.0 stylesheets and switch to the 2.0 stylesheets, there might be changes, even significant ones behind the scenes, but the output shouldn't surprise you.

  • Customizer friendliness. It should be easy to customize the stylesheets. That means they should be designed for reuse and they should be parameterized in useful ways.

Motherhood and apple pie, mostly.

HTML Goals
  • I'm targeting HTML(5) with CSS. If the right place to change the look-and-feel of a rendered page is in CSS not in HTML, then that's what you're going to have to do.

  • Support for (unobtrusive) JavaScript if it's necessary. If features like annotations and extended XLink support would benefit from JavaScript, then JavaScript it will be.

Works well in modern browsers, is usable in older browsers.

XSL FO Goals
  • XSL FO 1.1? Maybe?

  • Beyond general cleanup and removing support for processors that no longer exist, my explicit goals for XSL FO are a bit more, uh, amorphous.

Anyway, these are just my 0.0 release ramblings, don't read too much into them.


Wonderfull. Have been looking forward to this distribution for a very very long time.

Only fear is that I have to stick with the XSLT 1.0 version for a long time for a 10 year old DocBook project.

And now it is time to experiment with my new v2 toy. Thanks a lot.

—Posted by Jens Stavnstrup on 25 Aug 2011 @ 08:08 UTC #

Thanks, finally my last excuse to switch from Xalan to Saxon has vanished. So I guess I have to adjust my Ant toolchain. Thanks for the work, also pretty cool that you producing HTML5 now as output.

—Posted by Lars Vogel on 25 Aug 2011 @ 08:16 UTC #

I would like to use the docbook XSLT 2.0 for my custom XML with CALS tables. But my XML does not have the docbook db: namespace. How do I import the docbook XSL without changing my XML to have the docbook namespace? Is there a way to fool my XSL into thinking the source XML has the docbook namespace? I only want to use the CALS tables XSL code. Thanks, Jeremy

—Posted by Jeremy Odekirk on 25 Mar 2013 @ 03:43 UTC #

There's no easy way to do that. You'll have to edit the stylesheets to change the namespace to the namespace you're using, or remove the namespaces if you aren't using namespaces.

Alternatively, you could investigate writing your stylesheet so that it adds the DocBook namespace before it calls the CALS table code. But that might be more trouble than it's worth.

—Posted by Norman Walsh on 27 Mar 2013 @ 10:34 UTC #