“Playing fetch” with DocBook

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.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s