Re: [Boost-docs] [boost] Review request: auto-index tool

Subject: Re: [Boost-docs] [boost] Review request: auto-index tool
From: Barend Gehrels (barend_at_[hidden])
Date: 2011-01-24 23:17:22

Hi,

>> On 01/24/2011 02:02 AM, Paul A. Bristow wrote:
>>> ... elision by patrick...
>>> So I feel we need to encourage library authors to produce:
>>>
>>> 1  PDF version as well as HTML (and so use Quickbook?).
>>>
>>> 2  Quickbook and Doxygen reference section.
>>>
>>> 2  Doxygen comments in C++ code about everything. (Perhaps GSoC or
>>> Boost.Guild people could volunteer to do this?).
>>>
>>> 3  Auto-indexing of functions.,classes ... as standard. (So we need to
>>> get auto-index into next Boost release package).
>>>
>>> 4  Conventional word index - Indexing of words in the text.
>>>
>>> 5  A user-friendly Quickbook template so new authors can get going
>>> quickly.
>
> Perhaps others will volunteer to tackle the docs (you have to have a
> reasonable grasp of the library - I found I didn't have enough for
> Boost.Pool and would like some experts to correct and amplify my efforts.
>
>>   It seems like we not only need a user-friendly
>> Quickbook template, but a good tutorial document from someone that's
> fought
>> through this and has found success.
> I'm working on it  :-)
>
> (but listing all the many, many pits on can fall into (been there, done
> that) with inscrutable diagnostics is quite a job!)
>

To the useful list of Paul I would suggest that there should be many 
more examples within the boost docs. So:

6: Enough clear examples

We struggled too with generating the docs. But I feel now we have 
something useful combining Doxygen and Quickbook. I realize there are 
some other approaches, some of them translating to boostbook, some to 
quickbook, but that process (xslt) was hard.

So in short how now Boost.Geometry doc's are generated:
1) C++ is commented the Doxygen way
2) Samples are created, the Quickbook way (compilable, might go back to 
quickbook, callouts, etc. are possible)
3) Doxygen is called, producing XML (the configuration file has an 
alias, \qbk)
4) A specifically developed (work in progress) tool *doxygen_xml2qbk* is 
called, converting the doxygen XML to quickbook
5) quickbook is called the normal way (using bjam, go to 
boostbook,docbook,html)

This produces things as in:
http://bit.ly/gJSmaa
(follow the area link, or e.g. reference matrix - point)
(note it is work in progress)

I've added a sort of minimal sample showing the process, to that 
doxygen_xml2qbk tool, (currently) here:
http://bit.ly/eGYBf5

The essence is that:
1) quickbook is created, not boostbook
2) the quickbook is created as good as possible (using xsl this seems to 
be quite hard (at least for me)), showing all that Doxygen shows
3) quickbook can be intermingled within Doxygen comments, and those 
quickbook pieces can (partly to do) go anywhere in the generated 
quickbook, e.g.:

/*!
\brief A useful function
\qbk{[heading Example] }
\qbk{[apple] [apple_output] }
*/

the \qbk alias (defined in Doxygen configuration) gives also the 
possibility to use e.g. the quickbook [include ...] clause (to avoid 
many lines of qbk here), and/or can span different lines (as done in the 
sample in the trunk)

To define the place, the first argument of the alias(macro) might be a 
place-marker (e.g. before.synopsis)

4) the result is pure quickbook code based on doxygen comments and 
manually written quickbook markup.

Regards, Barend