Re: [PATCH 3/3] rev-list --min-parents,--max-parents: doc and test and completion

[Michael J Gruber <git@drmicha.warpmail.net>]

Jeff King venit, vidit, dixit 21.03.2011 11:54:
> On Mon, Mar 21, 2011 at 10:01:53AM +0100, Michael J Gruber wrote:
> 
>>>> +	Show only commits which have at least resp. at most that many
>>>> +	commits, where `--max-parents=8` denotes infinity (i.e. no upper
>>>> +	limit). In fact, 7 (or any negative number) does, but 8 is
>>>> +	infinity sideways 8-)
>>>
>>> I didn't quite parse this "resp." in the middle.
>>
>> Well, there are two options (--min-parents, --max-parents) which we
>> describe in one paragraph. Sooo...
> 
> I figured out what you were trying to say. I just had never seen the
> abbreviation "resp." before. I guessed it meant "respectively", but the
> syntax is all wrong.
> 
> Digging around via google, I was able to find that it is a mathematical
> term with a specific syntax, but one I had never seen before. Maybe I am
> just clueless and sheltered, but after 30-odd years of reading English
> (12 of which involved reading academic computer science papers!), I
> can't help but think it is not all that common and may confuse other
> readers. Add on top that it is usually used in parentheses, which helps
> make it more obvious what is going on.

In my community it is very common, which may partly be due to the fact
that there is a strong proportion of non-native speakers. It took it for
granted that it's a standard expression.

> 
> I really think "Show only commits which have at least (or at most,
> respectively) that many commits" says the same thing, but is way more
> accessible.

Sounds good, I'm happy with that. Resend or squash on apply?

> 
>>> That way it is obvious that "--merges" cancels a previous --min-parents
>>> on the command line (maybe the text should be "this is an alias for..."
>>> to make it clear that doing it is exactly the same).
>>
>> Yes, that is helpful. I have doubts about "alias" for. Without wanting
>> to sound elitist or something, I have the impression that we start
>> catering for users who understand "equivalent" more reliably than "alias".
> 
> I just wanted to make sure people didn't think "equivalent" meant "has a
> similar effect to" as opposed to "is exactly as if you did". But reading
> it again, I think "equivalent" is fine, and I see you picked it up in
> the latest series.

I may be wrong about what is common in this case, too. For me, "alias"
is foremost a technical term, and I would guess that many non-native
speaker know "alias" either in the technical sense or not at all, but
not so much in the common English sense. But either way is fine.

Michael