Re: [boost] [fusion] html docs woes

Subject: Re: [boost] [fusion] html docs woes
From: Joel de Guzman (joel_at_[hidden])
Date: 2011-07-16 19:12:00

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