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: Paul A. Bristow (pbristow_at_[hidden])
Date: 2011-09-07 09:02:47

> -----Original Message-----
> From: boost-docs-bounces_at_[hidden] [mailto:boost-docs-bounces_at_[hidden]] On Behalf Of
> Dave Abrahams
> Sent: Wednesday, September 07, 2011 12:29 AM
> To: boost-docs_at_[hidden]
> Subject: Re: [Boost-docs] 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.

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

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]