, Issue 28; 09 Nov 2025

Updates to the DocBook xslTNG Stylesheets and my XProc-for-DocBook repository.

Last Monday, I published xproc (for DocBook) and I’ve used it a fair bit since then. That lead to a few improvements, including a new shell script to run it.

What I discovered was that I was often doing this:

cd /path/to/xproc
./gradlew -Psource=/path/to/file.xml -Presult=/path/to/file.html html
popd

That’s silly. A script could do that. So I wrote xdocbook and added it to the repository. This is much nicer:

xdocbook file.xml

That worked fine until the first time I wanted some customization. So I added support for that too. It’s a bit of a hack and I think I can do better with a custom catalog entry. But it works, which was the short term goal.

Along the way, I discovered that I’d left some PRs and issues hanging about in the DocBook xslTNG Stylesheets repository. I think what happened was I got to a point where I wasn’t sure what to do, paused to think, and then forgot to come back to it.

Issue #648 reveals that I implemented percentage width (and depth) incorrectly. I was treating a width of 50% as half the intrinsic width of the image. That’s wrong. It’s very clearly documented that it’s supposed to be half of the available width.⊕A contentwidth of 50% is half the intrinsic size. Fixing that a potentially annoying backwards-incompatible change. But not fixing it means I’ve implemented the wrong semantics.

I decided to fix it, because it’s wrong. But I added a parameter, $mediaobject-percentage-of-intrinsic-size, that you can set to retain the old behavior.

“The available width” is kind of perilous for the stylesheets. They don’t have any way of knowing how wide the display is ultimately going to be. But there’s a nominal width, so we use that. (It’s 6 inches by default, but you can change it.)

And just this morning it struck me that inside a CALS table, we can do better. The table processing knows how wide each column is, as a fraction of the nominal page width, and can pass that down as a tunnel parameter. That properly fixes issue #581, which is nice.

There are a few other odds and ends too.