Re: [boost] Boost documentation format

From: Jeremy Maitin-Shepard (jbms_at_[hidden])
Date: 2007-06-25 13:06:49

"Peter Dimov" <pdimov_at_[hidden]> writes:

> 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. Both are intermediate formats that 
> are of no practical use without further processing. I admit that it would be 
> possible to make the .xml files viewable in a browser by using a stylesheet, 
> 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. 

In general it is not a very good idea to use a version control system to
store generated files, because they will waste space, and they must not
be edited anyway.

It seems that what is really needed is an easy way for anyone to
generate the documentation (in any of the supported formats, like HTML,
PDF, etc.) from the source files (boostbook or docbook or quickbook
files, or source code in the case of doxygen).  If there is not already
a command in the build system to do this either for all of boost or for
an individual project, then there should be one.

If special tools not distributed with Boost are needed, they should be
noted in an easy to find place on the Boost website.

-- 
Jeremy Maitin-Shepard