Re: [boost] How to handle generated html files with modular-boost and GIT?

Subject: Re: [boost] How to handle generated html files with modular-boost and GIT?
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2014-06-22 04:23:54

> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Andrey
Semashev
> Sent: 20 June 2014 13:17
> To: boost_at_[hidden]
> 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
[phone]