Re: [boost] [release] 1.69.0 deadline for new libraries approaching

Subject: Re: [boost] [release] 1.69.0 deadline for new libraries approaching
From: Edward Diener (eldiener_at_[hidden])
Date: 2018-10-23 19:29:25

On 10/23/2018 2:36 PM, Robert Ramey via Boost wrote:
> On 10/23/18 11:17 AM, Peter Dimov via Boost wrote:
>> Robert Ramey wrote:
>>
>>> And I place the html and pdf versions into the repo so users don't 
>>> have to build it.
>>
>> Placing the .html/pdf files into the repo is one - unquestionably 
>> modular - way to do it, but it does have its downsides.
> 
> Both true.
> 
> downside
> - "wastes" a lot of space
> - redundant - docs could get out sync with the code.
> 
> 
> upside
> 
> - current documentation is always available to the user.  In the two 
> libraries of mine - documentation is an important part and I don't think 
> the either would be usable without them.
> - only needs to be built on one machine no hassle for users
> - document build doesn't have to be "portable"
> - potential users can easily browse the documentation before they 
> clone/download the package.  This works well with github.  I think this 
> is very valuable - especialy for safe_numerics which most people don't 
> actually see the need for.  Call it a sales tool.

I am sure you know that github already has support for viewing the 
documentation via the github io mechanism, so your last '-' item is not 
really applicable to your argument.

My argument is simply that lots and lots of libraries use Boost Build to 
generate the docs, very often through the quickbook -> docbook -> 
pdf/html mechanism and unless we are going to continue to do it that way 
when Boost uses CMake we will eventually need a way to duplicate the 
Boost Build mechanism for creating the docs in CMake.

Nonetheless I continue to believe that the move to CMake by Boost should 
be achieved in small steps, so that we can assure success in one step 
for all libraries before we even think about attempting the next. I 
still have the same fear that trying to accomplish everything at one 
time will mean that nothing really will ever get done. I only added item 
5) to Peter's list because that is something we will eventually have to 
decide about.

I understand your own way of generating docs but I think this is 
irrelevant to the general discussion vis-a-vis Boost Build and CMake. I 
know you really do not believe that the solution is for everyone to 
generate the docs the way you do.

> 
> For me, this is was a pretty easy decision.
> 
> Robert Ramey