Re: V2 documentation format

From: Christopher Currie (Christopher_at_[hidden])
Date: 2004-02-02 10:49:21

>>First question is how does it look?
> 
> Really nice! Congratulations to you and Zbynek.
> 

I agree, it does look terrific. There are some minor errors in spelling, 
but nothing a little copy-editing won't cure.

>> The second question is what documentation format should be use. 
>> Zbynek has used PHP to automatically generate header and navigation
>> links, and I'd like to discuss if we're going to use that format,
>> or current html, or something else.

The only drawback is that it makes it harder to distribute the docs as 
pure html; users wouldn't be able to download the docs unless we put 
them through a php pre-processor first.

> I too find it a bit of an overkill to use PHP just to create the headers...
> I'm not familiar with docbook, so I'll refrain from commenting.

I tend to agree here. My personal vote is for DocBook, which I like a 
lot, and a fair amount of work has been done with BoostBook to create a 
unified look to Boost documentation, and to provide extensions that make 
sense in the context of Boost. Admittedly, the generated HTML doesn't 
look as nearly as pretty as what Zbynek has done. Fortunately, I think 
that can be fixed simply by creating a new XML stylesheet.

If desired, I can devote a little time over the next few days to convert 
the docs to BoostBook, using the improved structure that Zbynek has created.

Christopher