Over the past couple of days, I've fixed a hack in the documentation framework that has
bugged me for a while (I am about to start writing the chapter on writing docbook
documentation, and I was too embarrassed to admit to the hack in writing. :-)
I originally designed the documentation system so that people could easily write a
docbook.xml file containing a chapter of documentation. That works for most cases of
documentation except for sensors and sensor data types, in which you want people to be
able to write a docbook.xml file that would contain a section, not a chapter, and that
would be combined with all of the other section-level docbook.xml files into a chapter
for sensors and a chapter for sensor data types. So, I wrote a hack that special cased
these two situations and created two appendices to the user guide containing them.
Unfortunately, sensors and sensor data types are not the only kinds of Hackystat
constructs that should be documented as "sections" rather than chapters. For example, it
would be extremely useful for Reduction Functions to be documented via docbook, so that
developers could easily find out the primitive building blocks of telemetry (yes, there
is an online reference, which is nice, but a docbook chapter would be even nicer, as it
would allow things like interlinking to other chapters and so forth.) It would be nice
for each Hackystat command to have its own documentation, with a screen shot of its
invocation and sample analysis results. In addition, consider an application like
hackyApp_Pri, which supports an extensible set of "PRI Measures" and "PRI
Indicators"--shouldn't each of these constructs be allowed to have its own docbook
section as well?
To solve this problem, I've generalized the documentation system with a fourth volume
called the Reference Guide. This contains chapters where each chapter is made of
sections, and each section is derived from a separate docbook.xml file. The zillion
commits I made yesterday were in part done to reorganize the system so that the
"appendix" chapters in the user guide are gone, the special purpose code hacks to create
them are gone, and the definition xml files required to create these reference guide
chapters are in place.
I've just edited the Hackystat Dev Site home page to reflect this new organization, so
you can check it out at: <http://www.hackystat.org/>.
Cheers,
Philip
