Subject: Re: [boost] [release] 1.69.0 deadline for new libraries approaching
From: Peter Dimov (pdimov_at_[hidden])
Date: 2018-10-23 18:51:28
Robert Ramey wrote:
> > Placing the .html/pdf files into the repo is one - unquestionably
> > modular - way to do it, but it does have its downsides.
> Both true.
> - "wastes" a lot of space
> - redundant - docs could get out sync with the code.
- it complicates the process of creating and incorporating a pull request
that includes documentation fixes. The submitter sometimes doesn't know or
realize that the .html needs to be regenerated too, or knows it but can't
get the script to work; or he changes the .html instead of the source.
The usual process seems to settle into submitters just submitting patches
against the source (without having means to verify if the docs still build
after their changes) and then the author occasionally regenerating the
docs - if he doesn't forget, which he does.
But yes, it's a tradeoff that's worth it if you want users to have easy
access to your documentation after cloning the repo.
For Boost libraries, I myself just point people to boost.org/libs/mylib.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk