July 17, 2003

Software Documentation with DocBook, Part 2

<oXygen/>, while not bad, is not something I can get used to. It's written in Java which, in most cases at least, just plain sucks for desktop applications of this kind. It obviously relies on the Apache family of XML/XSL software, which is not exactly the best decision in terms of performance. It required an outrageous amount of memory, and took forever to transform a one-page XML document (although admittedly, the XSL stylesheets for DocBook are pretty monstrous).

So my next try was good old XEmacs, the world's best editor and an old aquaintance of mine (before it got replaced to edit Java with IDEA. But that was not a great experience, either .... out of the box it wasn't possible to validate the XML, since it relies on OpenSP. No problem, downloaded and built that, as well. Unfortunately, it failed to validate because it doesn't support referencing DTDs via URLs (that would be very unusal, I know, it's just about 99% of all XML files that do that). Downloading the docbook DTD and the accompanying files didn't help either - it complained about missing entity definitions. Sigh ... so the next thing to try is XMLSPY from Altova. Stay tuned.

Update: XMLSpy seems to suck as well - load the XML, pick the stylesheet, run the transformation - all I get is the very informative message "A template with this name already exists". Firing up the debugger kills my machine for about 10 minutes; when it finally finishes opening up three dozen windows, the message is ... "A template with this name already exists". OK, I think I'll return to UltraEdit and perhaps Saxon. (Did I already mention that MS IE can't run the XSL as well?)

Stefan Tilkov wants do do documentation for a software project with DocBook. The first post sound very optimistic, a later one a bit pessimistic. He is struggling with finding a good XML editor with integrated support starting XSL transformations. Besi...

Read more in Choosing the right tool for DocBook »