From: Joel de Guzman (joel_at_[hidden])
Date: 2007-11-01 19:00:44
Stefan Seefeld wrote:
> Eric Niebler wrote:
>> How are the HTML docs handled? Are the generated HTML files checked into
>> the website's SVN?
> The boost.python tutorial's html is in fact checked into the
> boost.python repository itself. I don't know about other libraries.
>> Seems odd to check generated files into version
>> control. Maybe the Documentation link on the Boost's home page could
> Not only odd, but error-prone. (I was just asked to check conflicts in
> an attempted merge from the last release branch to trunk, because the
> html in trunk was generated by a different tool than the one on the
> branch, resulting in many benign conflicts.
>> take you to a page that had links to automatically generated PDFs in
>> addition to the HTML.
> I see multiple issues here:
> 1) The packages are even bigger than necessary as they bundle
> documentation. IMO it would be good to split packages on that axis, too,
> i.e. provide documentation separately, as an add-on.
> 2) Since developers are not expected to have all the required tools
> installed, the produced docs are in the repository, too. The way I have
> seen this handled in other cases is that docs are only to be built (by
> default) on previleged hosts that have all the right tools set up. The
> results of such builds are then made available through the common website.
> (Of course authors *can* build html and pdf themselves, if they make
> sure they have the proper build environment set up first.)
I agree with all of Stefan's points. I think the only concern for
having the docs in there is that if a developer wants a snapshot
of (tarball, zip) the package downloaded, he should be able to get
the docs too. If it is possible to do 2 (above), a developer can get
a snapshot of the repository and have the docs auto-generated in the
process, then all is well.
-- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk