Documentation and text processing

["Alan M. Carroll" <am...@network-geographics.com>]

In the dev meeting there was an agreement that we would use Doxygen for reference and some other text system for more general documents. A concern was the ability to link from the general documentation to the reference (e.g., if an API call is discussed, that should have a link directly to the reference for that call).

As a starting point for dealing with this, I offered to provide my WikiVar Perl package. This is my version of WikiVar style text processing. It would enable putting text of the form

$ref "TSTxnHttpGetHeader"$

in to the general documentation and have it converted during post-processing to a link to that API call. I use it myself to generate corporate documentation, such as the transparency documentation[1]. The package works by doing a function lookup and then invoking other Perl subroutines (in the case above, "ref" would be used as a key to call a subroutine, passing it the argument "TSTxnHttpGetHeader"). The notation supports positional, named, and keyword arguments. The text limiter is run time configurable (e.g. %ref "..."%).

A bit of glue logic would be needed but I can write that easily.

There is some minimal documentation available[2].

[1] http://people.apache.org/~amc/tiphares/home.html
[2] http://people.apache.org/~amc/WikiVar.html