Re: [boost] Boost documentation format (was Re: Boost documentation)

From: Gennadiy Rozental (gennadiy.rozental_at_[hidden])
Date: 2007-06-25 16:33:06

"Peter Dimov" <pdimov_at_[hidden]> wrote in message 
news:014b01c7b748$f2894840$6407a80a_at_pdimov2...
> Gennadiy Rozental wrote:
>> "Paul A Bristow" <pbristow_at_[hidden]> wrote in message
>> news:002301c7b741$0798cc40$0200a8c0_at_hetp7...
>>> I think the weight of opinion is firmly behind keeping Quickbook as a
>>> favoured, but not exclusive, Boost docs tool.
>>
>> Let me clarify again my point:
>>
>> Boost should require BoostBook as a documentation format. This is the
>> format documentation should be kept in source control and delivered
>> with release.
>
> I don't disagree with the above; it's OK to have a Boost-wide requirements
> for documentation, and I personally have no opinion on which one it should
> be.
>
> However I should stress that *neither the current form of .xml nor .qbk is
> documentation* as far as I'm concerned.

It is. If we call it this way ;)

> Both are intermediate formats that
> are of no practical use without further processing.

Not nesseserily. but this is beyond the point.

> I admit that it would be
> possible to make the .xml files viewable in a browser by using a 
> stylesheet,

and it should be

> but currently they don't seem to be. CVS users of Boost should not be
> considered second-class citizens; they should have access to 
> human-readable
> documentation as well.

I don't agree. There multiple different formats we can produce from DocBook. 
HTML in chunks, HTML in one chunk, PDF, HTML help and so on. Which one do 
you believe we need to keep under source control.

I don't consider CVS users of boost first class citizen. They are kinda 
upper class. If you opted to deal with cvs version of boost, deal with doc 
generation in your favorite format. And I don't think this is a problem 
under regular circumstances. The fact that 1.34 took so long should be an 
exclusion. With regular - every 3 month - releases the need for direct cvs 
access by users should be minimal.

Gennadiy