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.