Boost logo

Boost :

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.


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk