Boost logo

Boost :

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]>

> 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.


Boost list run by bdawes at, gregod at, cpdaniel at, john at