After my post about DocBook 5 which I wrote from the hospital, with no connection to my Yamato to test most of the basis of it, today I started looking at working with DocBook 5 here, too.
This is mostly so I can resume working on the article I had to put on hold for surgery, but it’ll also work fine out as a way to start looking into what I was thinking of.
The first problem was to get good new Emacs to work with DocBook 5 files. Even the latest CVS version will still only support the old 4.x series “schemas”, and thus won’t support the new namespace aware DocBook 5. Luckily, I use Aquamacs on the laptop too so I already looked up how to support it. To make it more streamlined, for everybody me included, I decided to make it a step further.
If you’re an Emacs user in Gentoo and want to work with DocBook 5, just install app-emacs/nxml-docbook5-schemas and it will install the Relax-NG compact schema for DocBook 5 with support for XInclude (hurray for XInclude), and set up nxml so that it’s loaded properly, just restart Emacs (or find a way to make it reload nxml cache) and you’re set. Please note that nxml-mode decides which schema to use once you open the file in the buffer, so if you’re converting an old DocBook file to the new version, you’ll have to close the buffer and reopen the file.
Unfortunately xmlto does not seem to support DocBook 5 just yet, and it insists on looking for a DTD to validate the content. Even the latest version, which I bumped in the tree, fails to generate content out of DocBook 5. So I decided that xsltproc is good enough for me, and decided to make it possible to install the stylesheets as needed.
I’ve bumped app-text/docbook-xsl-stylesheets to the latest version and then created a new package, app-text/docbook-xsl-ns-stylesheets that use the new namespace aware stylesheets. Unfortunately for this to work, I also had to update the build-docbook-catalog script, that agriffis used to maintain… last touched in 2004. I suppose this is one of the things that should be quite more documented as to “Why? How? Who?” — there are instructions on how to release it but no documentation on why this is needed, how it was implemented and so on.
The script is very much abandoned and had quite a few hacks in it, one of which I removed because it wasn’t making any sense any longer (it was redirecting some old versions of stylesheets to the local copy, but not the most recent ones — such old versions don’t exist for xsl-ns for instance so it makes no sense to duplicate the redirections). Part of the reason why it was executed at every install/removal is not even relevant nowadays (stylesheets used to be installed with their version number, like it is done for DTDs, but this is no longer the case as they are not slotted), it should well be possible to just reduce the code needed to a simple function in the ebuild itself, rather than using such a bit-rotting script.
At any rate, I future proofed it a notch by making it possible to support xsl-xalan and xsl-saxon just by creating the proper ebuilds for the tree (I’m not interested in those yet so I didn’t create them).
I suppose one interesting thing would be to install Gentoo’s DTDs and Gentoo’s stylesheets through ebuilds too, but it’s unlikely to be easy or much useful as it is, so let’s not get there yet.
So anyway, I hope what I did today is going to be helpful to others to use DocBook 5 with Gentoo; if it was, appreciation tokens are quite appreciated, especially at convalescence time 😉