-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Joachim Faulhaber Sent: 05 November 2008 14:14 To: boost@lists.boost.org Subject: [boost] proposal interval container; ITL moved to the boost sandbox
<big snip>
Next I am going to write boost style html-documentation.
I'm surprised you have the strength left ;-)
From the boost web page I don't see a clear recommendation for a preferable way of doing that. Handcoded? Generated with BoostBook? Is there a reference library that has an exemplary standard documentation?
As a joint (junior) author of one large library, I have no hesitation of recommending Quickbook as an author-friendly system. From a familiar WikiWiki language, it produces nice html and also even nicer pdf with no extra work. It's weakness is the very complex toolchain, but if you copy other peoples examples (and watch out for the bizarre syntax) you will find the actual writing fairly painless. If you have lots of classes etc you can use DOxygen as well if you wish. Make sure you can re-generate existing documentation before you start: this will check you have got the toolchain set up right. For examples, see the nice'n'friendly Quickbook documentation - done with Quickbook of course ;-) For outputs, see the Math Toolkit and Units documentation, both some 500 pages - more than you will produce I suspect. I strongly recommend using 'Quickbook embedded in source code as comments' as a way of keeping your selected snippets of source code synced with the documentation. Many of the Math examples are done this way. It means that if you read the example code, you have the Quickbook commentary, or if you read the documentation, the (sElected) C++ code is shown in nice boxes. Have fun! Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com