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

From: Rene Rivera (grafikrobot_at_[hidden])
Date: 2007-11-01 15:55:45

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.

Checking in generated documentation that is also generated as part of 
the BoostBook chain is a waste. It will not be used from the POV of the 
release since the docs will end up in the boost-root/doc location, not 
in the libs/<library>/doc location. Other types of generated docs do 
need to be checked into SVN as otherwise they will not show up in the 
release. Hence until everyone switches to BoostBook we will have HTML 
docs in SVN.

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

Perhaps, not a concern for this release though. Since we clearly can't 
change this now ;-)

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

Historically the release manager has built the BoostBook docs that go 
into the release, and are checked into SVN. We also want to have up to 
date docs available, hence it's always been a goal to have a 
documentation build server. Such trunk & release built docs would be 
available in the same way the docs are available now in the beta site.

-- 
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org - grafik/redshift-software.com
-- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo