Boost logo

Boost :

Subject: Re: [boost] [fusion] html docs woes
From: Joel de Guzman (joel_at_[hidden])
Date: 2011-07-17 06:28:30


On 7/17/2011 5:44 PM, Phil Richards wrote:
> 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...

I don't know what you mean by a "different breed", but many Spirit
users, especially those following the Spirit lists, use the SVN trunk.
In fact, we advocate that and motivate the users to contribute to the
code and docs.. And by doing so, we catch mistakes early, among other
benefits. We do our best to always keep the trunk as release stable
as possible.

Perhaps Spirit users are a "different breed" ;-)

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

Yes.

Regards,

-- 
Joel de Guzman
http://www.boostpro.com
http://boost-spirit.com

Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk