From: Michael J Gruber <git@drmicha.warpmail.net>
Date: Thu, 06 Aug 2009 08:48:59 GMT
Subject: Re: [PATCH 2/2] git-rev-list.txt: Clarify the use of multiple revision arguments
Message-ID: <4A7A98FB.7070104@drmicha.warpmail.net>
In-Reply-To: <7vd47adxfq.fsf@alter.siamese.dyndns.org>

Junio C Hamano venit, vidit, dixit 05.08.2009 18:42:
> Michael J Gruber <git@drmicha.warpmail.net> writes:
> 
>> diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt
>> index 847cc7d..40ca276 100644
>> --- a/Documentation/git-rev-list.txt
>> +++ b/Documentation/git-rev-list.txt
>> @@ -66,6 +66,13 @@ command:
>>  means "list all the commits which are included in 'foo' or 'bar', but
>>  not in 'baz'".
>>  
>> +So, the resulting set of commits is the union of 'foo' and 'bar',
>> +intersected with the complement of baz. The order of arguments is
>> +irrelevant: first, the union of all positive refs (those without
>> +'{caret}') is taken, then the result is intersected with all negative
>> +refs (i.e. with the complement of the union of all refs which appear
>> +with a preceding '{caret}').
> 
> It seems to me that the first sentence just repeats what the previous
> sentence that we can see in the context with different fuzziness.
> 
> I am guessing that the reason you are patching this is because you felt
> that the existing "list all the commits which are _included in_ 'foo' or
> 'bar', but not _in_ 'baz'" uses "be included in" without defining what it
> really means (i.e. "reachable by following the ancestry").
> 
> I however find the "union of 'foo' and 'bar' intersected with the
> complement of 'baz'" similarly lacking.  The sentence equates commit X
> with the set of commits that are reachable from X, without explaining that
> is what it is doing.
> 
> To me, this feels much worse than the original.  When you say commit X,
> the reader must guess if you are talking about the single commit, or the
> set of commits reachable from it by following the ancestry chain.
> 
> How about rewriting it a bit more without repeating?

Yes, I tried to be minimally invasive, which is also why I split the
patch in two (correction + addition). I really prefer your rephrased
version. Feel free to squash in/ask me to resubmit/whatever suits you.

Michael