[boost] Re: Singleton Library Ready for Review

From: Joel de Guzman (joel_at_[hidden])
Date: 2005-02-07 00:04:46

Jason Hise wrote:
> Jonathan Turkanis wrote:
> 
>>> Should I start working on the documentation then?  If so, what medium
>>> should I use?
>>>   
>>
>> Definitely. In some respects the documentation is more important than 
>> the code.
>>
>> See http://www.boost.org/more/writingdoc/index.html. You should probably
>> consider using Boost.Book: http://www.boost.org/doc/html/boostbook.html
>>
>> Make sure the docs are complete enough that people can easily evaluate 
>> the
>> design of the library. But also remember that the design may change, 
>> so trying
>> to perfect the documention too soon could end up wasting some time.
>>
> It looks like there would be a sharp learning curve involved in trying 
> to use boostbook.  Although I think that such documentation would 
> eventually be great, I think that it would take too much time to put 
> together now while people are trying to evaluate my library.  Would a 
> plain text tutorial be sufficient for the time being?

How about quickbook? It is now in the CVS tools directory.

<<What is QuickBook?>>

QuickBook is a WikiWiki style documentation tool geared towards C++ 
documentation using simple rules and markup for simple formatting tasks.
QuickBook extends the WikiWiki concept. Like the WikiWiki, QuickBook 
documents are simple text files. A single QuickBook document can 
generate a fully linked set of nice HTML and PostScript/PDF documents 
complete with images and syntax-colorized source code.

Features include:

     * generate BoostBook xml, to generate HTML, PostScript and PDF
     * simple markup to link to Doxygen-generated entities
     * macro system for simple text substitution
     * simple markup for italics, bold, preformatted, blurbs, code
       samples, tables, URLs, anchors, images, etc.
     * automatic syntax coloring of code samples
     * CSS support

For point of reference, the entire set of xpressive's documentation at:
http://boost-sandbox.sf.net/libs/xpressive

was generated from a the single text file:
http://tinyurl.com/6h464
(full link: 
http://cvs.sourceforge.net/viewcvs.py/*checkout*/boost-sandbox/boost-sandbox/libs/xpressive/doc/xpressive.qbk)

Up-to-date documentation for QuickBook can be found in CVS at 
boost/tools/quickbook/index.html .

Cheers,
-- 
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net