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: Mateusz Loskot (mateusz)
Date: 2010-09-03 12:28:06

On 03/09/10 11:40, Barend Gehrels wrote:
> A few notes: - the reference Mateusz created is currently a bit
> stripped, this is for development, to not be overwhelmed by 100ths
> functions to be filled in, and also convenient for review to not see
> 100ths of functions which are not yet documented. But the larger
> version will come back, of course

(I've talked with Barend on google talk, let's summarise...)

Barend,

Do you mean we're going to bring all public interface in the docs?
I'm quite sure we are, but it's good to confirm.

> - even then not all which is listed there is (completely)
> documented.

Yes, indeed.

> - the reference pages can be quite documented, (possibly) having code
>  snippets, behavior, complexity, images,

As I've suggested, I'd rename Snippets to Examples.

> - I found the xsl procedure quite hard, and not yet complete. After
> pondering a while I decided that C++ is my tool. So I left the xsl
> approach for interpretation of Doxygen, and am using now a relatively
>  simple C++ tool using RapidXML. This works great and can be easily
> customized up to the level we want. Of course xsl is still there
> because part of the QuickBook->BoostBook->DocBook->html conversion
> process, and also the reference section is still in XML as there is
> AFAIK no quickbook counter part

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.

(from our chat)

I need to learn more about your appraoch, but (...) One thing concerns 
me, does the RapidXML appraoch mean that two generators are going to be 
maintained?

I understand your point about XSL, it's complex and not easy, but I'm
kind of worried to not to brew too many generators within Boost as it
may lead to lack of synchronisation with Boost in general, but perahps
it's just me worrying unnecessarily

Yes, I see your point and I agree, it looks good.
I think it's all right as long as it allows seamless integration with 
Boost docs as that's the primary goal as far as I understand.

You know, the XSL appraoch actually states a "yet another generator" 
which I've stolen from very local sources of one library in Boost
The XSL based generator does not seem to be an official Boost-wide tool.

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

> Please let me know what you find.

Your docs output looks very good to me.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net