Feb 242006

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.

Tweet about this on TwitterShare on Google+Share on LinkedInShare on FacebookFlattr the authorBuffer this pageShare on RedditDigg thisShare on VKShare on YummlyPin on PinterestShare on StumbleUponShare on TumblrPrint this pageEmail this to someone

  5 Responses to “23.02.2006 The Beast Documentation Quest (2)”

  1. I can’t tell from your tone if you’ve yet found what you need, but if you haven’t, Synopsis might be it, at least as far as extracting documentation from C++ sources.

  2. I also use Synopsis.
    But I didn’t found any tool that really match my needs. And I think that starting another documentation project would be totally useless. Instead, we should probably design some source code description (AST, like in Synopsis ?) standard XML schema, and some library (and other languages bindings) to handle matching documents. Then, people could start various parser/formatter projects that would match their needs and work together.

  3. Well one of the bigger problems is that there isn’t a C or C++ parser out there, as what we write down into .c or .cpp files isn’t C or C++. – it is C or C++ *before beeing processed by the preprocessor. This bring lots of challenges for a parser 🙁

    Anyway some people (including me), trying to improve gtk-doc as far as possible to generate better docs. IHMO using the same doc-utile and thus allowing x-refs inbetween is crucial for a paltform (GNOME).

  4. Python has a lot of support modules for parsing both different programming languages[1] and structured text formats (be it XML or something else), so maybe something could be done by cobbling together some already existing Python stuff and writing the rest from scratch?

    [1] I’m not sure about C++ though.

  5. Ahem, I just noticed that the Synopsis tool mentioned above can both be used from Python and parse C++:

 Leave a Reply

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>