For reasons outside of my control, several individuals have informed me that they wish to use DocBook for document generation. Mind you, i'm more than comfortable with "traditional" HTML layout for these sorts of things, but yes, i can see where having a nice generic SGML layout for a document does make a great deal of sense. That part i'm very comfortable with.
Where things break down for me is with the various consumers of said docbook generated content. i hateses them. i hateses them so much.
You see, the problem is that the docbook generation system uses a combination of XSL and a pile of still warm chicken entrails to convert the "raw" docbook formatted XML into something less XML-y. This system is designed to generate one layout of all documents. i know this because of delightful little details like how elements store styling information for the HTML constructs. (What? You DON'T want <H2> tags to have "clear:both"? Are you MAD!? What possible thing could you ever want to put next to a document!? i mean, aside from a table of contents, images, a sidebar, example code, or really anything other than the loving document WE generated for YOU?)
Honestly, i've had to replicate vast tracts of XSL in order to do silly things like make pages semantic so i can apply simple CSS to them or not use the kludgey, pre-baked navigation systems. …or change context for sections to NOT be the current one and instead pull from the top, or other various things you'd really, seriously, think someone would have converted to a parameter. Don't even get me started on what an incredible pain it is to generate a full table of contents on output page without resorting to an external script to "fix" several pages.
Oh, and those bits about DocBook being "simple" and "easy to configure"? Don't you believe them.
Sorry, man. I've tried to put hooks in to minimize the amount of customization necessary. Clearly I've blown it in some places. Still, I'm pretty sure the navigation stuff is parameterized and I'm not sure why you wanted to change the context. What on earth did you have to fix in the table of contents?
Well, my biggest problem was that I had some folks who wanted to significantly rejigger things from the standard DocBook format. The general flow of things they wanted was a TreeView table of contents that listed the entire document (expanded to the current section) displayed on the left hand side. In addition, they wanted the document to effectively begin with the first page (not the table of contents) and a few other things.
I've been able to get most of the way there by doing a fair bit of post processing on the files into PHP templates and doing some cheats to get things working the way I need them to (e.g. transcoding index.html into a set of javascript objects that are then composed by YUI's Treeview.
I also understand that a lot of the things that bug me aren't because of docbook, but more the problems inherent in XSLT. Like I said, I REALLY like the idea of docbook being a general formatting schema, and frankly, I really should just get off my duff and code up a transform framework that uses something like python, PHP or perl so that it's more extensible. Provided I get the time, I probably will.
Thanks!
Save This Page
For what it is worth, I never had any issues with Javadoc (although I never attempted any heavy lifting with it either). It just worked like I expected and produced much nice output automagically than I wanted to put effort into creating myself.