Re: [boost] [1.35] Where to place PDF versions of docs?

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.

Regards,
-- 
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net