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.