Geometry Boost List: [ggl] [Fwd: [Boost-docs] Translating Doxygen defgroup to Quickbook]

Subject: [ggl] [Fwd: [Boost-docs] Translating Doxygen defgroup to Quickbook]
From: Mateusz Loskot (mateusz)
Date: 2010-02-28 12:27:01

Hi,

I had a chat with Barend today about handling some of aspects
of Doxygen documentation. Here is a summary of the topic
and question I posted to boost-docs (included below)

http://lists.boost.org/MailArchives/boost-docs/2010/02/4008.php

-------- Original Message --------
Subject: [Boost-docs] Translating Doxygen defgroup to Quickbook
Date: Sun, 28 Feb 2010 16:51:13 +0000
From: Mateusz Loskot <mateusz_at_[hidden]>
Reply-To: Discussion of Boost Documentation <boost-docs_at_[hidden]>
To: boost-docs_at_[hidden]

Hi,

Doxygen supports @defgroup command [1] that can be used to make
a group of related elements. While combining Doxygen-generated XML
with Quickbook, I've noticed that this information is dropped - no
pages or sections are generated for defgroup.

I found that the libraries seem to handle the defgroup thing on their
own, in a custom way. It suggests there is no support for it in
Quickbook. So, I investigated Boost Asio docs in details as it looks
to me as best example of such solution.

What Boost.Asio does is
- generate the Doxygen-encoded docs to XML output
- transform the XML to Quickbook file reference.qbk [2]
using the xsltproc tool and custom stylesheet reference.xsl [3]
The whole process is fired with a simple script [4]

For example, header /boost/asio/read.hpp defines "async_read" group [5]
that gathers all overloads of the async_read function.
The documentation generator explained above puts all async_read versions
under common node [6] in HTML output from Quickbook.

The Boost Asio manner of handling with the defgroup thing
sounds very well.

However, before I'll adopt it for Boost Geometry, I'd like to know if
there is any better or let's say recommended way to achieve this.
Perhaps Quickbook has got native support of Doxygen defgroup, etc.

I'd be thankful for comments.

[1]http://www.stack.nl/~dimitri/doxygen/grouping.html
[2]https://svn.boost.org/trac/boost/browser/trunk/libs/asio/doc/reference.qbk
[3]https://svn.boost.org/trac/boost/browser/trunk/libs/asio/doc/reference.xsl
[4]https://svn.boost.org/trac/boost/browser/trunk/libs/asio/doc/doxy2qbk.pl
[5]https://svn.boost.org/trac/boost/browser/trunk/boost/asio/read.hpp?rev=58761#L31
[6]http://www.boost.org/doc/libs/1_42_0/doc/html/boost_asio/reference/async_read.html

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org
_______________________________________________
Boost-docs mailing list
Boost-docs_at_[hidden]
http://lists.boost.org/mailman/listinfo.cgi/boost-docs
-- 
Mateusz Loskot, http://mateusz.loskot.net
Charter Member of OSGeo, http://osgeo.org