Re: [boost] [fusion] html docs woes

Subject: Re: [boost] [fusion] html docs woes
From: John Maddock (boost.regex_at_[hidden])
Date: 2011-07-17 04:44:48

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