I'm merging [72977] to release (<https://svn.boost.org/trac/boost/changeset/72977>) and am given a headache by the fact that Fusion has its HTML docs checked in. The docs are automatically generated from the qbk files so committing them to svn is strictly unnecessary, AFAICT.
Why is this a problem?
- Any change to any qbk file results in a huge number of diffs to the HTML docs (due to changed ids), resulting in a huge commit, long upload times, long download times, long merge times.
That's pretty much fixed in the latest quickbook version, which is generating remarkably few spurious changes IMO.
- It leads to unnecessary merge conflicts when merging commits from trunk to release. I'm going to have to regenerate the docs on the release branch and upload them all ... for no benefit!
Granted, but it's not that much hassle revert the HTML folder and rebuild prior to commit.
Can Fusion be changed to build its html docs as a normal part of Boost's doc build procedure like other Boost libraries?
That also has issues: * Crazy long build times, IMO xsltproc just doesn't scale well to "build all of Boost's docs" - testing documentation changes can take almost forever. * No way for folks to read the HTML until it's actually released. * One size fit's all chunking scheme - it works for small libraries - but IMO larger libraries with complex documentation hierarchies would be rendered almost unreadable (I'm thinking of Boost.Math here). * No way to insert any library specific XSL options - for example the Math library uses .png's for html and SVG's for PDF output which requires some fancy XSL footwork that other libraries wouldn't want I'm sure. We could obviously move to a distributed scheme where doc/Jamfile.v2 just cycles through the individual libraries docs - in fact I don't why we haven't done this anyway ages ago, but it still doesn't solve the "can't read the trunk's docs" issue. Regards, John.