Paul A. Bristow wrote:
Mateusz Loskot wrote: I'm working on documentation of Boost Geometry based on Quickbook and I've prepared a prototype:
http://mateusz.loskot.net/tmp/ggl/qbk/
What I'm doing is manually porting the content from Doxygen-based (http://geometrylibrary.geodan.nl/) plus restructuring, reformatting and completing it with missing details.
I'd like to ask everyone who is interested in Boost Geometry library for comments, impressions and suggestions of improvements.
The Reference is one of the most important section I'd like to master, so please share your comments on the form and completeness of the concepts specification, for example:
This is looking nice - but so was the Doxygen based version.
The problem with Doxygen version is that it lacks of important details. So, by the way of updating the documentation, we've decided to move to Quickbook format. AFAIU, it is a preferred format for Boost docs.
I believe (and found 'eating my own dogfood' -especially the SG plot project) that the Doxygen produced Reference section is complementary to the more textual sections that you are writing.
Yes, that's right. I agree Quickbook work means more or less manual rework of what Doxygen generates.
Several libraries use both, see Boost.Units, Accumulator, (and of course the NotAlibrary SVGPlot Soc 2007/vizisualization)
I have checked Acccumulator docs and I have to admit its reference is nothing more to me than a headers/code browser. It includes very little information. The Units does it better and I've just learned that pages like this http://www.boost.org/doc/libs/1_42_0/doc/html/boost/units/unit.html is generated from Doxygen comments...hmmm
and I think this is much the best way to go, especially as you have already done the tedious task of adding Doxygen style comments to the code, so that you (and readers) would lose much if you don't provide it.
Yes, now I can see the point and that it's possible to combine both, Quickbook and Doxygen. Sounds as the best option indeed.
I found it was wise also to generate Doxygen only version first to check you don't have any warnings - its quicker that way.
Doxygen lint-like functionality is helpful, indeed.
Finally I would say that I found the Quickbook embedded code system very, very useful. This ensures that the examples cannot get out of sync with the code. and I found numbering sections algorithms_append_hpp_1, algorithms_append_hpp_2 ... and also using algorithms_append_hpp_output to show some or all of the output.
I put the output in a C comment like this [...] which can be referenced by the QuickBook text.
Right, sounds like a very useful feature. Paul, thank you for your suggestions. It opens new approach that seems much better than hand-only crafted docs. Best regards, -- Mateusz Loskot, http://mateusz.loskot.net Charter Member of OSGeo, http://osgeo.org