Boost logo

Boost :

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>> writes:
>> On 1/9/16 6:45 PM, Louis Dionne wrote:
>>> Rene Rivera <grafikrobot <at>> 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, and
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é.-

Boost list run by bdawes at, gregod at, cpdaniel at, john at