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