In order to look for a new documentation tool for Beast, i set out a list of requirements that had to be matched:
a) We need to generate reference documentation from C and C++ source code comments.
b) Since we also need to process ordinary documentation files (say an FAQ) that involve lots of text and occasionally graphics, Tex-info syntax is to be preferred over XML-style markup (well – actually *anything* is preferable over XML-style markup for lots of human digestible text) if at all possible.
c) We need to generate documentation from introspection tools (e.g. bseautodoc.c spews out documentation for object properties, signals and channels).
d) The source code comments should use the same markup style that is used for ordinary documentation and design documents (e.g. the Beast FAQ or the Beast Quick Start Guide).
e) We need to be able to generate decently looking HTML for the Beast website.
f) We need to be able to generate manual pages – nothing too sophisticated, covering roughly the feature set of man(7) on Linux is more than sufficient.
g) We need a runtime documentation format with support for “live documentation”, this was one of the reasons to go with GtkTextView in the original documentation. Basically “live” here means, runtime documentation displayed by a running Beast instance, e.g. triggered from the “Help” menu, should be able to provide links/buttons/activators that can trigger the running Beast instance to play back documentation example songs.
h) Taking (b) to the extreme, writing documentation should be as easy as possible, maybe even as easy as writing documentation with OpenOffice Writer and exporting it as HTML. Of course, this would conflict with (g)… or – would it?
i) Automatic external cross-linking should be supported, e.g. to all the documentation sections offered at http://developer.gnome.org/doc/API/. Especially within the reference documentation, automatic link markup would be good to have, without authors having to dig up links or add markup to the relevant keywords.
j) The tool-chain required to build documentation should be available from a reasonably standard system, such as the current Debian stable.
k) Something similar to the custom macro definition feature of Tex-info as described in The Beast Documentation Quest (1) should be offered by the new documentation system as well if at all possible.
The above requirements at hand, i looked around quite a bit to find a documentation tool that would allow me to fulfil all or most of them.
It turned out that (a) and (g) definitely were amongst the harder ones, while (i) was mostly solved already by the old documentation system with regards to link indexing. There, we used a Perl script to extract various kind of (source code identifier, developer.gnome.org/doc/API/-link) tuples from developer.gnome.org. This scrip even covered enum values, something that gtk-doc does not generate own index lists for.
One of the next things i was to find out, was that many tools don’t deliver HTML output as nice as that generated by gtk-doc. But then, even the very long-term plans for gtk-doc do not include extension towards C++ parsing…
In general, C++ parsing isn’t one of the tasks easily covered. As far as i could figure, there is no decent free C++ parser (including comments) usable for documentation purposes other than Doxygen. Luckily, Doxygen is a reasonably standard tool (j) and also supports ‘@’-style markup that looks Tex-info alike (b) and generates documentation in multiple output formats (amongst them HTML and manual pages). Unfortunately i could not get the Doxygen HTML output to look anywhere close as decent as gtk-doc generated HTML pages. That included attempts at sophisticated CSS modifications and even hacking it’s documentation generation abilities. At closer inspection, Doxygen also did not fully fit what i had in mind for a general purpose documentation tool to cover, i.e. (b), (c) and (k). It should be noted however that Doxygen supports link index imports in a Doxygen specific format that can be used to enable automatic external linking (i) with some effort.