Re: [Boost-docs] HTML version of documentation - Store using SVN or leave users to build

Subject: Re: [Boost-docs] HTML version of documentation - Store using SVN or leave users to build
From: Dave Abrahams (dave_at_[hidden])
Date: 2011-09-08 16:59:03

on Wed Sep 07 2011, "Paul A. Bristow" <pbristow-AT-hetp.u-net.com> wrote:

>> My view is: don't check generated files into source control.  People
>> have a tendency to submit patches against them, or worse, modify them
>> directly.
>
> I thought you might say that ;-)
>
> (which is why I asked!)
>
> But that doesn't answer the need for people to be able to read the
> html without generating it themselves (requiring Quickbook, Doxygen
> Autoindex, bjam ...)
>
> If people can't quickly scan the docs, they can't decide if the
> library is of any interest to them.
>
> (If a library is accepted, then there isn't a problem of course, html
> docs are available as the normal Boost docs, but during discussion and
> review...)

I agree.  What to do after you decide not to check generated files into
source control is a separate question.  

One issue is that we have a horrible documentation toolchain that makes
it hard to write/check/experiement with documentation.  Maybe something
like http://readthedocs.org could help us if we could contribute a
backend
<http://readthedocs.org/docs/read-the-docs/en/latest/builds.html>.

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com