Re: [boost] [fusion] html docs woes

Subject: Re: [boost] [fusion] html docs woes
From: Phil Richards (news_at_[hidden])
Date: 2011-07-17 05:44:50

On Sun, 2011-07-17 at 07:12 +0800, Joel de Guzman wrote:
> 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.
[...]
> Those are very valid and good points, Eric.
[...]
> - 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.

For an "end-user", I suspect that as long as the final boost tar-ball
contain the documents, they don't care about what is in SVN.

In fact, I'd suggest that most end users who download boost could even
cope with the idea of having a boost-1.47.0.tar.gz and a
boost-docs-1.47.0.tar.gz
(The former being an export of the SVN tree, the latter being the
generated docs.)

People who play around with the boost SVN source tree are, I suspect, a
rather different breed from most users of boost...

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

Does this mean that every time you edit the source to the docs and
commit it, you perform a regeneration of the docs and commit them at the
same time?

Phil
-- 
Phil Richards, <news_at_[hidden]>