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-03 06:40:03

hi all,

Mateusz Loskot wrote:
> Yesterday I managed to get first good results of processing Doxygen
> XML output to Quickbook/Boostbook documentation.
>
>
> (...)
> Generally speaking, I've reviewed docs of most of Boost C++ Libraries and
> I decided that Boost.Asio is the best example to follow. Boost.Asio is a
> complex library,
> it heavily uses Doxygen comments and, IMHO, it integrates them with
> Quickbook/Boostbook

Last month I have worked on Boost.Geometry documentation using the 
Doxygen/QuickBook approach which Mateusz started this year.

The new version can be here: <http://bit.ly/aeFqXP>

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
- even then not all which is listed there is (completely) documented. I 
will give some deep links below of things representable
- the reference pages can be quite documented, (possibly) having code 
snippets, behavior, complexity, images,
- 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
- the generated documentation is still Doxygen/Quickbook compatible (be 
it that for snippets and some other things this is not possible) but I 
don't know if it is necessary to keep this
- I'm currently working in the subfolder "qbk" and left the quickbook 
folder as it was, copying necessary files from there
- not all pages from the original "human written docfiles" are already 
there, some (also some already processed) will be added later
- most things are committed, such that you can see documentation source 
tags; I will review my changes on intersection and this will be 
committed today or tomorrow

Some deep links:
<http://bit.ly/aT6dbW> for documentation on area
<http://bit.ly/boi5PX> for documentation on intersection, also based on 
Hartmut's questions last week
<http://bit.ly/a2f5dZ> for documentation on the geometry::point class
<http://bit.ly/b3rBlu> for documentation on the 
BOOST_GEOMETRY_REGISTER_POINT_2D macro

Please let me know what you find.

The doxygen interpretation tool (doxygen_xml2qbk) is currently in 
<http://bit.ly/an158r>

Finally, I'm traveling coming month, most of the time, so there will be 
periods that I'm not reading my mail.

Regards, Barend

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osgeo.org/pipermail/ggl/attachments/20100903/7af12033/attachment.html