-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Andrey Semashev Sent: 20 June 2014 13:17 To: boost@lists.boost.org Subject: Re: [boost] How to handle generated html files with modular-boost and GIT?
On Friday 20 June 2014 12:28:46 Paul A. Bristow wrote:
I've started to proof-read Vladimir Batov's Boost.Convert library and correct a (very few) typos etc.
I've had some troublesome experience with building docs with Boost.Math and this is similar (but much smaller).
So what do I do?
I think auto-generated files should never be committed. This bloats history and checkouts, adds problems when committing changes and doesn't offer any benefits. Also this ignores any possible changes in the build tool chain and stylesheets and resources, if you commit them as well.
The built documentation is mostly targeted for users, and for users we already have docs on the website. The ones who use libraries from git (which are mostly library maintainers) will have to setup the tool chain for building the docs. This is already a requirement for maintainers since you would typically build the docs after you modify them - at least to verify that it still builds. And getting QuickBook to work is not that difficult, really.
But most developers (let alone the users) don't now have Quickbook, Doxygen, Autoindex and Inspect set up. I think we need to standardize the setup of *all* these tools so everyone has them all. And a .gitignore /html in each library so that developers can build the current docs if they want to without upsetting GIT?
Even if you are not a maintainer and don't want to build it, QuickBook is quite readable on its own.
Hmmm. I prefer my html ;-) Although Boost.Math may take a coffee-break to generate :-( Anyway Vladimir has removed the convert /html from GIT and we are now getting along fine :-) Daniel - yes please add convert to the documentation build. Thanks for your helpful views. Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 01539 561830