DocBook XSL: The Next Generation

Volume 4, Issue 37; 25 Jul 2020

A new implementation of transformations for DocBook in XSLT 3.0

Yesterday, I posted a short note about the new DocBook xslTNG Stylesheets. I wanted to get something out and to mark the 1.0.0 release day, but I didn’t have the time (or the foresight) to get this post ready for publication on the day.

The goalThe CSS that’s included delivers (I hope) a clean and clear presentation, but I am not a graphical designer by trade. I’d be delighted to see what actual designers can do (a la CSS Zen Garden). Improvements to the presentation, or entirely alternate styles, would be very much appreciated! of the stylesheets is to produce clean, semantically rich HTML(5) that can be beautifully rendered with CSS (and a dash or two of JavaScript, if you wish) in the browser. I’ve done my best in all cases to make sure that the presentations are accessible. If you find something that isn’t accessible, please report it.

I made the 1.0.0 release yesterday morning because I was scheduled to deliver a presentation about them for a Balisage “tech check” session. That presentation is online now if you want to see it (or the DocBook source). Whether it makes a lot of sense without the narration is a little hard to predict. Some highlights from the talk:

  1. The stylesheets support extended links (links with multiple targets)
  2. The styelsheets do this by supporting XLink extended links (including linkbases)
  3. The extended links have a compact, unobtrusive presentation if JavaScript is available but fall back gracefully to an inline list in other environments, including print.
  4. The stylesheets support the notion of “local conventions” for markup, a last-in-a-series transformation that can turn your markup into proper DocBook just before the standard stylesheet processing begins. In this case, I have a simple(r) format for entering the extended links that’s transformed into full XLink for the stylesheets.
  5. I also showed annotations, which present as modal dialogs with JavaScript but also fall back gracefully. (The non-JavaScript online rendering needs a little work, but that’s the plan.)
  6. The stylesheets support an XInclude fragment identifier scheme when parse="text" that allows you to specify search strings for the beginning and the end of the text to include. That makes your document references much less brittle.
  7. The paged (or chunked) rendering of a document supports keyboard navigation and a “fly out” table of contents on every page (if you want one).

Those are all fun things. The stylesheets also do the mundane job of transforming 387 of the 416 elements in DocBook. The missing elements are related to assemblies, which I just haven’t implemented yet, and some new synopsis markup proposed for DocBook 5.2 that I don’t think is quite finished. There’s a coverage report that tracks progress towards 100%. That page also lists the test suite results. There are (at the time of this writing) 1,557 tests in the test suite, all passing.

I sort of assume that if you’ve got this far, you know what XSLT is for and if you care about transforming DocBook with these stylesheets, you can figure out what to do next. The guide tries to be helpful. (I hope it succeeds! Feedback most welcome.)

This is obviouslyComing soon, I hope! begging to be implemented in an XProc pipeline, but I didn’t have time to finish my implementation and write these stylesheets and write the Balisage paper that motivated them all in July. Alas. I will go back and address that deficiency as quickly as possible.

In the meantime, there are a few other options for running them. My thinking being that usability trumps most other concerns. No matter how cool they are, if you can’t get them to work, you won’t use them.

Chapter 2 describes four ways to run them:

  1. The distribution includes a jar file and the core dependencies. You can run the jar (java -jar …) directly. It takes the same command line arguments as Saxon, but will do convenient things for you like setup the catalog, resolvers, and extension functions.
  2. The distribution includes a Python script that also takes the same command line arguments and also sets up the environment. What it does in addition is work with Maven (which you must have installed) to automatically download the required dependencies and configure the class path.
  3. There’s a build file for a Docker container and an outline of instructions for how to use that. I don’t think that’s ready for prime time among folks who aren’t already familiar with Docker, but if you are, I’d be very interested in hearing your feedback.
  4. And, of course, if you’re already comfortable configuring your Java environment to run applications, you can just do that. I do highly recommend making sure that the jar file that ships with the stylesheets is on your classpath. The XInclude and image properties extension functions are required for some features.

I have decided to pursue print formatting (making paged media, i.e., PDFs) with HTML+CSS instead of XSL-FO. I appreciate that this may be disappointing, but I don’t have the time to do an entirely separate set of XSL-FO transformations right now. The project is open source, so if you feel like doing it (and its test suite, and its documentation), go for it!

I’ve published a PDF (formatted with Antenna House) of the presentation I gave yesterday as an example. I plan to publish a PDF of the guide soon.

Share and enjoy!