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-04 14:15:06

  hi Mateusz,

>
> Actually, as I've mentioned, the XSL approach is nothing official in
> Boost. It has been incorporated by Boost.Asio as a custom generator used
> within Boost.Asio only (AFAIK). So, having no official tools in Boost,
> if Boost.Geometry finds its own way to make its docs well-looking and
> well-incorporated with Boost documentation, I'm sure it's fine.

OK, cool.

> Now, could you summarise how can I use your tool?
> I'd like to start updating the docs content ASAP, so a bunch of
> guidelines would help.

Sure, that will help. It is good to document the documentation ;-)
There was a doc/qbk/readme.txt and I have extended it. Note that as long 
as Boost.Geometry is not in trunk, some files have to be copied...

In summary, the process is as following:

1) doxygen should be installed, if not already done
2) quickbook should be installed, if not already done, including the 
xsl-s for boostbook
3) bjam should be installed , if not already done
4) rapidxml (it is small) should be downloaded and put under 
.../other/programs/doxygen_xml2qbk/contrib/rapidxml-1.13
5) doxygen_xml2qbk should be compiled, using MSVC or gcc, there is a 
solution and a jamfile there now, added them today.

The binary goes in .../release (MSVC) or somewhere deeper (bjam), leave 
it there or copy it where appropriate (this might be enhanced, see below)

6) if it is compiled, goto .../libs/geometry/doc/qbk
7) there is a batchfile and a linux shellscript there, containing the 
process, but it is basically:
a) run doxygen (still run from the original folder above, and with the 
same Doxyfile, be it that it is modified now)
b) process all group* xml files with the tool, see batchfile which are 
currently processed
c) run bjam to run quickbook

8) the scripts contain path references to doxygen_xml2qbk, see above. So 
that might need a change. Note that the scripts might be obsoleted by 
doing everything in bjam, that would be a welcome enhancement
9) run it and the documentation should be generated

Ad b) Still the Doxygen groups are used to group functions, however I 
moved all the source-code-comments to define them to separate 
headerfiles, because they are not important in the source header files. 
Their text is NOT used in the generated QuickBook documentation anymore, 
it is function/class level. However, I found the groups still 
convenient, each group generate a separate qbk file.

More guidelines are necessary, involving macro usage, etc, but I've 
currently not enough time to write that out, it will come later.

Regards, Barend