|
|
Boost : |
Subject: Re: [boost] proposal interval container; ITL moved to the boost sandbox
From: Paul A Bristow (pbristow_at_[hidden])
Date: 2008-11-05 10:22:50
>-----Original Message-----
>From: boost-bounces_at_[hidden]
>[mailto:boost-bounces_at_[hidden]] On Behalf Of Joachim Faulhaber
>Sent: 05 November 2008 14:14
>To: boost_at_[hidden]
>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_at_[hidden]
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk