Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Mathias Gaunard (mathias.gaunard_at_[hidden])
Date: 2013-10-11 06:02:49

On 11/10/13 00:13, Niall Douglas wrote:
> On 10 Oct 2013 at 14:58, Robert Ramey wrote:
>
>>> Documentation like this is generated by preprocessing Doxygen XML
>>> output  to integrate it into Boostbook and have a good look for C++
>>> references.
>>
>>> It has most of what you can expect from Doxygen + the Boostbook stuff
>>> which gives better cross-referencing than simple Doxygen.
>>
>> Hmm - I looked at DOxygen and found it lacking for what I wanted.  I'm
>> also disappointed in the Doxygen generated documentation in boost which
>> to me mostly parrots the source code.  On the other hand, I think the
>> approach (literate programming) has promise but it seemed to me that
>> one would have to add a lot to Doxygen to generate what I would like
>> to see.  Maybe the "missing magic" is already in on our web site somewhere.
>> Basically I don't see where we can coordinate Boostbook with Doxygen.
>> Perhaps you could include the link which explains this.
>
> Boost.Geometry contains a utility called doxygen_xml2qbk which
> converts Doxygen XML into Quickbook.

Boostbook comes bundled with an XSLT stylesheet to convert Doxygen XML 
to Boostbook.
There is also this utility for doxygen to quickbook, but I don't know 
how it compares to the stock doxygen to boostbook.

I find it nothing short of astounding that experienced Boost developers 
don't understand how the Boost documentation toolchain works.

The toolchain is

Doxygen XML + Doxygen HTML (for LaTeX formulae) -> Boostbook XML
Quickbook (Wiki-style syntax) -> Boostbook XML

Boostbook documents can then be linked together simply by XInclude. 
Boostbook is then converted to Docbook and then HTML+CSS.

Boostbook is an extension of Docbook specifically designed to 
cross-reference C++ code. It has also an extension for Concepts.