On 7/17/2011 4:38 AM, Eric Niebler wrote:
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.
- It makes viewing a changeset all but impossible because the meaningful changes are lost in the noise of meaningless diffs to automatically generated files.
- 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!
Can Fusion be changed to build its html docs as a normal part of Boost's doc build procedure like other Boost libraries?
Those are very valid and good points, Eric. Well.. - I'm not sure of the "normal part of Boost's doc build procedure". We always regen the docs even before quickbook became predominant (remember quickdoc?). So, it's been the policy for Spirit, Fusion and Phoenix too, as well as quickbook itself while I was maintaining it. - The rationale is that it puts the burden on the committer, but saves the user from having to regen the docs herself, along with all the hassle of installing the tool-chain and all. What we wanted was for the user to have access to the latest docs snapshot that is always synced with the code. That's the real benefit. - We have had no problems merging spirit docs anymore since quickbook V1.6, which does not generate so many differences anymore. Perhaps it's time to revisit the policy. There are pros and cons to either approach but I personally would prefer carrying the burden for the sake of the user being presented the latest docs every time. Regards, -- Joel de Guzman http://www.boostpro.com http://boost-spirit.com