See: http://blogs.testbit.eu/timj/2006/02/22/21022006-the-beast-documentation-quest-1/ (page moved)
Around 2002, we (the beast project) started to put together the various bits and pieces for a makeinfo based documentation system. We ended up using texinfo markup because it’s not as hard to read and write for humans as XML is, and you can easily define your own macros to aid you in semantic markup.
E.g. if you wanted to markup a menu item path as such, you simply define @menu{} to mark things up as desired and then use it like:
Use @menu{/File/Save As...} to save a files with arbitrary names.
Documentation was needed mainly in three formats: HTML for the website, manual pages for the executables, and in a specific (.markup) format for a GMarkup-based parser that served as a front end to GtkTextBuffer text and tags. This .markup format is actually what Beast used (and currently still uses) as its primary documentation which can be displayed by GtkTextView widgets (.markup files contain tag definitions that define GtkTextTags with specific property settings and tag spans that apply these to text regions). So to generate documentation, we basically did (simplified for brevity):
1) write doc.texi with texinfo markup,
2) generate XML markup from doc.texi with makeinfo --xml,
3) generate the target formats with xsltproc [markup.xsl|html.xsl|man.xsl].
And for display, we did:
4) parse .markup file at runtime with GMarkupParser,
5) create GtkTextTags and adjust their properties from the parsed tag definitions,
6) create a GtktextBuffer to be displayed by a GtktextView, and apply the GtkTextTag spans.
On top of all this, we parsed our source files with a perl script to extract source code documentation, and generated .texi files from that. We used a perl script instead of using gtk-doc, because it was hard to use back then and because we wanted to use texinfo markup instead of SGML markup for our documentation (the escaping required by SGML/XML really sucks for source code sequences).
So far so good.
But then, roughly 2 years ago, we started to get serious problems with our documentation system, basically due to instabilities of the --xml mode of makeinfo. Other annoyances were that we couldn’t document our newly added C++ code, and that GtkTextView/GtkTextBuffer, albeit having a rich set of markup facilities, has no support for <table/> markup in any form (and probably never will). That, and a bit of maintenance lack in our .xsl files led me to look around for suitable alternatives…