Re: [boost] [range] Should html docs be checked in?

On Sat, 28 Dec 2013 03:16:17 -0800, Neil Groves wrote:

On Sat, Dec 28, 2013 at 10:22 AM, Mostafa wrote:

...

Can the maintainer(s) of range answer this question that came up in the documentation ML:

On Sat, 28 Dec 2013 02:09:06 -0800, Daniel James wrote:

On 28 December 2013 00:15, Mostafa

...

wrote:

...

If html files, or any other files for that matter, are auto-generated then why are they included in the repo? The reason I ask because this difference in boostbook version causes a lot of extraneous noise when I do a git status. Instead of the three html files I was expecting to be modified when I changed a qbk file there are 153 extra html files that show up as modified.

For many libraries they aren't. It's up to the library maintainer how they're managed. What you can do is rebuild the documentation from a clean checkout and commit that, then later edits shouldn't result in so many changes.

I have been generating the html and checking it in. However if there is a way to transition to a better system I am all for it. I'm catching up on the changes to the version control and the working process before making a renewed effort to clear some outstanding trac tickets. I'm sorry that I've been a little slow in catching up with the process changes. In the long-term I expect to converge on optimal working practice.

In the interim, if there is something I can do in the short-term that helps, please let me know. If you simply require permission to do what you believe is right, then please go ahead with your change. I'm happy to try a change and revert if it goes wrong.

From Daniel's reply and my very elementary understanding of Boost's build process, I think it's only necessary to revision the quickbook files, and that all files generated from the latter need not be revisioned. <MyTake> Generally, I don't think it's a good idea to revision auto-generated files, since minor differences in the generator version may result in harmless but extraneous deltas between the generated files that were revisioned in the repo by doc-generator-v1.0 and the ones generated by someone else like me who generated the same files using a newer (or slightly older) doc-generator-v1.1. This can get really cumbersome because a revision diff (i.e., git diff) will display all the harmless auto-generated diffs in addition to the real ones. </MyTake> Anyways, to make a long story short, I just wanted to tweak some docs and make a pull request when I ran into this other issue. I thought I should bring it up only because I think it represents an unnecessary obstacle to ad-hoc contributors. Mostafa