"Playing fetch" with DocBook
Posted by David N. Welton Wed, 29 Aug 2007 16:34:00 GMT
A while ago I wrote about the idea of "playing fetch" - meaning chasing after programming "sticks" that are basically makework. I am starting to get the feeling that the documentation system that I chose for Hecl is one such stick. I've been trying to document that lcdui commands that Wolfgang created last year. They're really cool, and give you access to pretty much everything you can do from Java, but cranking out these docs is sure time-consuming. Here's an example:
<refentry id="lcdui_date">
<refnamediv>
<refname>lcdui.date</refname>
<refpurpose>Date/Time widget for lcdui forms</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>lcdui.date</command>
<arg choice="opt">
-date
<replaceable>date/time in seconds</replaceable>
</arg>
<arg choice="opt">
-label
<replaceable>label</replaceable>
</arg>
Once you finally slog through and create the documentation, it's very flexible, because you have not created just formatting instructions, but actually described each piece of the text.
But... look at how often things get repeated. Aside from the repetitive XML tags, lcdui.date is more or less there three times. Ugh. Emacs + psgml mode helps some, but I still get the feeling I got suckered into doing something that should only be attempted by Big Corporations or at least large, well established projects that can afford to send people off to spend lots of time producing this kind of documentation.
Yeah, this is how I've ended up seeing DocBook. Seemed like a good idea at the time, but the sheer volume of poo that I have to write to do basic things seems an awful lot like makework. And, of course, folks tell me to use a special-purpose docbook editor for this, and that takes another 5 hours to get installed, configured, and working for the particular docbook variant that's been mandated.
DrBacchus, I suggest you take a peek at XMLMind (www.xmlmind.com). Download it and in ten minutes, you'll be cooking with gas! Check out my review at WritersUA.com for a in-depth study: http://www.writersua.com/articles/xmlmind/index.html
I tried xmlmind, and it seems ok. I don't see how it would really get me around the slog of markup up each piece of text, but it does have a more WYSIWYG approach than emacs/psgml, so it's easier to navigate around. A big problem for me is that I have includes that grab bits of source code, and it wants to permanently integrate them into the document. That might be ok if I were to continue using the program, but I still prefer to edit the included programs outside of the document.
I'm also preferential to open source software where possible.