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