Re: [boost] [fusion] html docs woes

Subject: Re: [boost] [fusion] html docs woes
From: Robert Ramey (ramey_at_[hidden])
Date: 2011-07-16 21:23:52

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.

Isn't this only a problem because the docs are generates as one Looong
document with all the chapter numbering accross all of boost?  If
documentation for each library were done separately (that is by
running bjam from withing the libraries doc directory) Then the ripple
would be limitied to that one library.  This would be compatible the
movement to the "modularization/decoupling" of boost libraries.

> - 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!

To me this suggests that we sould re-visit the "merge to release"
concept.  SVN does a "merge".  What we really want is a "copy"
to relese.

> Can Fusion be changed to build its html docs as a normal part of
> Boost's doc build procedure like other Boost libraries?

Personally I like the way fusion does things. It permits me to browse
the html documentation in the release branch on my own or some
other machine without having to rebuild the docs - which for me
has always been a very tiresome process.

I think its probably time to re-start the discussion about the
evolution of boost. I realize that the last boostcon talked about this.
A lot of this stuff - e.g. quickbook - just sort of happened - not
necessarily a bad thing - but it might be time to take a good look
at how we do stuff to see if we can streamline the process. I
know it's a pain - but as time goes on it becomes more attractive
to consider changing things.

Robert Ramey