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 😉
I don’t think it would be very practical to have to maintain ebuilds (thus, tarballs) of our DTDs and other XML-related files.Why not? For the same reasons that we don’t offer ebuilds of our GuideXML documentation — all the updates to the files would require a tremendous amount of time to maintain. Imagine trying to stabilize these things when updates are a few times a day, several times a week/month, and even more per year.Well, I guess in the case of our DTDs and stylesheets, those don’t get as many updates as our actual .xml files do, but still.Besides, all these files are available via wget anyway, or even by checking out gentoo/xml/htdocs/ from (anon)CVS.
I know they are available, but DocBook DTDs and stylesheets are also available.I think DTDs would be more important than stylesheets, to actually provide packaged. The reason for this is to allow an easy, offline way to validate the documents one is writing.And with stylesheets it should be possible to have a gorg-like preview without having to actually have a full checkout of the tree.But as I said, I don’t want to go there yet.
Glad to hear you are out of the hospital and on your way to recovery.