Re: [boost] Test build for 1.56 available

Subject: Re: [boost] Test build for 1.56 available
From: Edward Diener (eldiener_at_[hidden])
Date: 2014-07-08 11:58:56

On 7/8/2014 10:07 AM, Andrey Semashev wrote:
> On Tuesday 08 July 2014 09:42:37 Edward Diener wrote:
>> On 7/8/2014 9:04 AM, Andrey Semashev wrote:
>>>
>>> Personally, I think distributing pre-built docs as a separate package is a
>>> better option. Building docs locally require toolchain that is not
>>> distributed or built with Boost, so offering users to build the docs
>>> themselves is not quite practical. At the same time, I'm sure most users
>>> won't use bre-built docs and just go online, so packaging docs with the
>>> sources seems like a waste.
>>
>> I believe most users will execute the index.html in the top-level
>> directory and expect to be able to view the documentation for any Boost
>> library in which they are interested from the Libraries link there. To
>> think that we will distribute versions of Boost without this is foolish IMO.
>
> Do you actually use pre-built docs? I don't. Neither do most of my coworkers.
> I don't see why cutting down the archive I need to download by more than a
> half is foolish.

I am fine with the main distribution not having the docs as long as 
there is a separate docs download. The end-user should always have the 
choice of a central HTML index.html as now in order to view Boost 
documentation, or a PDF file with all the documentation, or viewing docs 
online.

I do not think it is viable that the end-users should now be expected to 
view docs only online for Boost libraries.

I also heavily agree with nearly everyone that generated documentation 
need not be part of git, although I would not rule it out for library 
authors who want to add it to git. As an example for Boost PP Paul 
created all the documentation in straight HTML format and it is updated 
on git whenever changes are made; it is not generated from Quickbook, 
BoostBook, doxygen, or anything else. For generated documentation from 
Quickbook etc., only the .qbk files and support files to build the doc 
need be on git.