Subject: Re: [boost] ATTENTION: Library requirements..
From: AgustÃn K-ballo BergÃ© (kaballo86_at_[hidden])
Date: 2016-01-10 18:05:37
On 1/10/2016 7:51 PM, Louis Dionne wrote:
> Robert Ramey <ramey <at> rrsd.com> writes:
>> On 1/9/16 6:45 PM, Louis Dionne wrote:
>>> Rene Rivera <grafikrobot <at> gmail.com> writes:
>>> It would be straightforward to require that doing `cd doc && b2` generates
>>> the documentation into `doc/html`, with index.html as an entry point.
>> You might think it would be straightforward - but it's not. The
>> toolchain is long and finicky.
> ??? How is it more difficult to require `cd doc && b2` to generate the
> documentation rather than having it in place already? You already have
> to do `cd doc && b2` for libraries that integrate with the rest of Boost
> anyway.. There must be something I'm not getting.
In order for `cd doc && b2` to work, one first need to have all the
dependencies in order. This alone is a considerable amount of work (see
nobody should go through that much trouble just to see html docs.
>>> Committing pre-generated documentation is a big no-no, at least for me.
>> I'm aware that doing so is redundant. BUT it provides anyone who
>> want's to browse boost just to do so directly, without building
>> anything. For example, anyone can just start browsing the repo
>> master branch without doing downloading or building anything. This
>> is huge for new users of boost.
> The way I see it, there should be a separate branch, say XYZ, which contains
> the documentation. This branch would simply need to be kept up to date with
> the documentation of every Boost library, which could be done by doing
> `cd doc && b2` in library's doc/ directory, and then copying the result
> to the right place. If someone wants to store the pre-generated documentation,
> this the Jamfile in `doc/` could just do nothing.
>> The extra space used seems a small price to pay for this benefit.
> It's not just about extra space. Source control is for _source_ files, not
> generated stuff. I don't want generated files to appear in the commit history
> of a code branch (but another branch like gh-pages is fine).
By way of example, this is the kind of noise committing generated
documentation can yield:
-- Agustín K-ballo Bergé.- http://talesofcpp.fusionfenix.com
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk