Re: [boost] ATTENTION: Library requirements..

Subject: Re: [boost] ATTENTION: Library requirements..
From: Robert Ramey (ramey_at_[hidden])
Date: 2016-01-10 01:10:23

On 1/9/16 6:45 PM, Louis Dionne wrote:
> Rene Rivera <grafikrobot <at> gmail.com> writes:
>
>>
>> [...]
>>
>> 1. A library is required to have HTML documentation.
>> 2. A library *can* integrate into the global Boost documentation.
>> 3. If a library doesn't do #2 it *must* provide prebuilt HTML documentation.
>>
>> Hence, even though Predef uses quickbook, it's never done #2. Therefore
>> Predef does #3
>
> Can't a library provide a Jamfile that generates the documentation, even if
> that documentation does not integrate with the global Boost documentation?

Many libraries do not "integrate with the "global Boost documentation"

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

> 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 extra space used seems
a small price to pay for this benefit.

Robert Ramey