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