[boost] Re: Documentation

From: David Abrahams (dave_at_[hidden])
Date: 2004-06-11 12:17:43

"Reece Dunn" <msclrhd_at_[hidden]> writes:

> David Abrahams wrote:
>>"Reece Dunn" <msclrhd_at_[hidden]> writes:
>> > David B. Held wrote:
>> >>If we're going to demand uniformity in licensing, should we also
>> >>demand more uniformity in documentation?
>> >
>> > I agree on this. At the moment, we have the docs written in HTML,
>> > those in BoostBook format (like Boost.Any and the BBv2 docs) and the
>> > Spirit docs which have their own format.
>>
>>And others; we used ReST for the iterator library.
>
> It should be fairly easy to adapt the ReST/SpiritDoc/whatever
> translation phase to generate BoostBook instead of HTML.

Yeah, especially since docutils (ReST) already contains a DocBook
generating backend.  It can also be done with XSLT from the ReST XML
generator.  But ReST doesn't contain ways to represent many of the
C++-specific logical elements of BoostBook, IIUC.

>> > As far as I understand it, the BoostBook tool is relatively new and
>> > has a learning curve, so it will take some time to migrate the docs to
>> > this format.
>>
>>And it requires writing in XML :-( or translating to it :-|.
>
> XML is essentially a stricter version of HTML. 

I thought the main thing was that it is extensible.

> The main problem I see is porting the existing HTML-based docs to
> BoostBook. The others can be generated using a BoostBook generator
> (not sure how easy it will be for each format).

There's no advantage to translating into BoostBook, AFAICT, unless
we're going to stick in its special logical elements.  We can always
just use a common .css if you just want a similar look.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com