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