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.