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: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2014-06-20 08:16:43

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'd hope just to be able to GIT commit  (but there will be added files so
> "git commit -a") and "git push".

'git commit -a' adds the modified files to the commit, it doesn't add any new 
files. If you only keep the original source files in git, this command does 
what is needed, unless you created a new .qbk file.

> (But what about obsolete files like html/boost/convert_id999999.html that
> should be deleted?) .
> 
> This seems a muddle, so should we remove the /html folder from GIT using
> gitignore?

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.

> However this would mean that users would have to generate the html (and
> assumes that all the tools like Doxygen and autoIndex are setup right - an
> unwelcome requirement).

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.

Even if you are not a maintainer and don't want to build it, QuickBook is 
quite readable on its own.

> And what about .log files - it seems very useful and reasonable to have them
> live in /doc but be ignored by  GIT?
> 
> Could/Should there be a global entry in top level /modular-boost/.gitignore
> to exclude all .log files?

Not sure what log files do you mean, I don't have any. Is it a product of your 
scripts?

> (I'd also like to put .bat or .sh files to build docs etc here too - there
> are various options in building and automatically dated log files are nice
> to have. )

I think there are scripts in some of the submodules. Probably adding them to 
.gitignore is not a good idea.