Re*: Tilde spec - befuzzled

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 29, 2012, 19:13 UTC
Message-ID: <7v8vjltpv1.fsf_-_@alter.siamese.dyndns.org>
In-Reply-To: <4F4DF096.9050905@op5.se>

Andreas Ericsson <ae@op5.se> writes:

Show 21 quoted lines

> On 02/28/2012 08:20 PM, Junio C Hamano wrote:
>> Thomas Rast<trast@inf.ethz.ch>  writes:
>> 
>>>>> '<rev>{tilde}<n>', e.g. 'master{tilde}3'::
>>>>> A suffix '{tilde}<n>' to a revision parameter means the commit
>>>>> object that is the<n>th generation grand-parent of the named
>>>>> commit object, following only the first parents.
>>>>>
>>>>> Hang on, *grand*-parents?
>>>>> ...
>>>
>>> Perhaps we should reword it as "n-th first-parent ancestor"?  Barring
>>> confusion about the position of the dashes, that leaves little room for
>>> error.
>> 
>> I think we could either go "easier to read but not precise"
>> 
>> 	... that is the<n>th generation (grand-)parent of ...
>
> (grand-)parent and ancestor are interchangeable while the parentheses
> remain, although the former looks a bit clumsier in text.

Ok, then something like this...

-- >8 --
Subject: Documentation: do not assume that n > 1 in <rev>~$n

We explained <rev>~<n> as <n>th generation grand-parent, but a reader got confused by the "grand-" part when <n> is 1.

Reword it with "ancestor"; with the "generation" and "following only the first parents" around there, what we try to describe should be clear enough now.

Noticed-by: Luke Diamand <luke@diamand.org>
Helped-by: Thomas Rast <trast@inf.ethz.ch>
Helped-by: Andreas Ericsson <ae@op5.se>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/revisions.txt |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index b290b61..1725661 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -101,7 +101,7 @@ the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file.
 
 '<rev>{tilde}<n>', e.g. 'master{tilde}3'::
   A suffix '{tilde}<n>' to a revision parameter means the commit
-  object that is the <n>th generation grand-parent of the named
+  object that is the <n>th generation ancestor of the named
   commit object, following only the first parents.  I.e. '<rev>{tilde}3' is
   equivalent to '<rev>{caret}{caret}{caret}' which is equivalent to
   '<rev>{caret}1{caret}1{caret}1'.  See below for an illustration of