Re: [boost] [fusion] html docs woes

Subject: Re: [boost] [fusion] html docs woes
From: Daniel James (dnljms_at_[hidden])
Date: 2011-07-17 05:50:46

(reordered slightly to make replying easier)

On 17 July 2011 09:44, John Maddock <boost.regex_at_[hidden]> wrote:
>
> * 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.
> * 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.

There's no need to build all the documentation together. For example,
the geometry documentation is handled separately. Although I do need
to clean up and check in my build script.

> * No way for folks to read the HTML until it's actually released.

I upload the trunk documentation on the sourceforge sandbox site every
time I build it, and there are redirects in subversion to take you
there.

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

The problem is that boost build always builds the documentation under
the directory from which it was run:

https://svn.boost.org/trac/boost/ticket/3240