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

From: Matias Capeletto (matias.capeletto_at_[hidden])
Date: 2007-06-25 12:59:47

On 6/25/07, Peter Dimov <pdimov_at_[hidden]> wrote:
> 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.

In my opinion release version must include both xml and html versions
of the docs.
We should store only the xml in the svn repository so the project size
is more user friendly.

> 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.

Good point. But I think we should not bloat the repository. What about
a adding a boost_docs tree with the last snapshot of the
documentation.

Best regards
Matias