Re: [boost] Help request, boost docs

From: Vladimir Prus (ghost_at_[hidden])
Date: 2007-06-21 01:04:03

Matias Capeletto wrote:

> On 6/20/07, Vladimir Prus <ghost_at_[hidden]> wrote:
> 
> Hi Vladimir,
> 
>> Douglas Gregor wrote:
>> > I would strongly advise that everything go into Quickbook format. It's
>> > far easier to write documentation in Quickbook than Boostbook, and
>> > Quickbook gives us more options.
>>
>> What options? Since you've authored Boostbook you must know better,
>> but I still don't see the value in using home-grown documentation format.
> 
> Have you tried Quickbook?
> It is an impressive tool. (I really think that it can be use for
> others things in the future beside boost). It is a lot easier to
> maintain, to read, to write, to share.
> 
> Some of the options that are included in Quickbook and not in Boostbook
> are:
> 
> * Support for code import. I will be very unhappy with out this
> feature. In the review of Boost.Bimap we find a lot of typos in docs
> examples. Every bit of code that appears in y docs now are in
> libs/bimap/example, and are tested with boost.build before I do any
> commit. You can not understand the value of this feature til you use
> it.

Such a support can be added to BoostBook via a tiny script or a tiny
C++ program that takes code and produces XML corresponding to it.
 
> * Support for macros

XML entities work just fine.

> and templates. 

Is it actually that much needed?

> * Simple markup for italics, bold, preformatted, blurbs, code samples,
> tables, URLs, anchors, images, etc.

I guess this is not "option" that quickbook provides, since Docbook allows
this too, and "simple" is subjective.

- Volodya