Re: HTML version of documentation - Store using SVN or leave users to build

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

> I have been revising the work of Pierre Talbot who has just finished his GSoC works on a Checks
> library, ready for a formal announcement that the project is open for public view, comment and
> feedback.
>
> He has worked diligently and produces some excellent documentation using Quickbook, Doxygen and
> AutoIndex that build both pdf and html versions.
>
> I have been loading both html and pdf versions up to the long suffering SVN.Boost.org server, but
> watching it upload a lot of small files, I am concerned at the load this may be placing on the
> server. (about 9 Mbyte, 2300 files, 170 folders).
>
> Past practice has been to expect the user to build his own local version of the html docs using
> bjam, but I am aware that not everyone (all too few people?) have the full toolchain of Quickbook,
> Doxygen and AutoIndex working to make this possible.
>
> So we have a something of a dilemma - load the fully html version, or find that many people will be
> unable/willing to read the docs at all.
>
> Or rely on just the (about 2 Mbyte) pdf version - all of which has to be downloaded every time it is
> viewed (compared to the html where only that pages read are downloaded)?
>
> Any views on the best (or least worst) course of action?

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.

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