Subject: Re: [boost] [fusion] html docs woes
From: John Maddock (boost.regex_at_[hidden])
Date: 2011-07-17 04:44:48
> I'm merging  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.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk