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

Subject: Re: [boost] [range] Should html docs be checked in?
From: Mostafa (mostafa_working_away_at_[hidden])
Date: 2013-12-28 06:43:02

On Sat, 28 Dec 2013 03:16:17 -0800, Neil Groves <neil_at_[hidden]>  
wrote:

> On Sat, Dec 28, 2013 at 10:22 AM, Mostafa  
> <mostafa_working_away_at_[hidden]>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  
>> <daniel_at_[hidden]>
>> wrote:
>>
>>  On 28 December 2013 00:15, Mostafa <mostafa_working_away_at_[hidden]>
>>> 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