Geometry Boost List: [ggl] [doc] New draft of Reference based on Doxygen-to-Boostbook

Subject: [ggl] [doc] New draft of Reference based on Doxygen-to-Boostbook
From: Barend Gehrels (barend.gehrels)
Date: 2010-09-04 05:27:44

  hi Mateusz,

Thanks for your summary ;-)

>
>> - the reference pages can be quite documented, (possibly) having code
>>  snippets, behavior, complexity, images,
>
> As I've suggested, I'd rename Snippets to Examples.

No problem, will be done.

>
> Perhaps I owe some explanation, especially to new folks on the
> list: mentioned XSL-based generate of Quickbook documentation has been
> stolen from Boost.Asio and customised (work still in progress) for
> Boost.Geometry.

Sure, it was (or seemed) basically a good idea. And there is also an XSL 
process to translate Doxygen to BoostBook (instead of QuickBook) within 
Boost. The last one is not our choice because we want QuickBook. The XSL 
in general is hard and in some cases limited (AFAIK), and besides that 
most C++ programmers do not have all XSL skills. At least I don't.
One of the things done here is e.g. the combination of 
template-parameters and their concept descriptions, and the function 
arguments and there descriptions. Will probably be hard in XSL. Another 
thing is outputing the headers and convenience headers, and therefore on 
the fly parse another (header-inclusion) file, which is uncommon or not 
possible in XSL.

On the other hand, the Doxygen ALIAS constructs I'm using now, and 
QuickBook macro's (a similar thing), make all things more structured, 
and less verbose in the sources (but more cryptic). They are new and can 
probably also be processed by XSL, like they are now by RapidXML.

>
> Shortly, the question is: to (re)invent Doxygen to Quickbook generator 
> or not.

Yes, that is a good summary. Stated as this it actually does not belong 
to this mailing list, so I reformulate the question here as "to start a 
Doxygen to Quickbook generator for Boost.Geometry or not?".

My opinion is that the RapidXML/C++ tool I drafted has less lines, is 
more powerful, more readable and easier extendable than the XSL. 
Actually, I can't make the docs, as they are looking now, without it. So 
I advocate a yes on it. See also my answer to Luke about to make it more 
generic than for Boost.Geometry alone.

Another question is:
Do we still want to keep Doxygen HTML output or not.

>
> Your docs output looks very good to me.

Thanks, Barend