Re*: Tilde spec - befuzzled

Andreas Ericsson [off-list ref] writes:

On 02/28/2012 08:20 PM, Junio C Hamano wrote:

quoted

Thomas Rast[off-list ref]  writes:

quoted

quoted

quoted

'<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 [off-list ref]
Helped-by: Thomas Rast [off-list ref]
Helped-by: Andreas Ericsson [off-list ref]
Signed-off-by: Junio C Hamano <redacted>
---
 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

On 29/02/12 19:13, Junio C Hamano wrote:

Andreas Ericsson[off-list ref]  writes:

quoted

On 02/28/2012 08:20 PM, Junio C Hamano wrote:

quoted

Thomas Rast[off-list ref]   writes:

quoted

quoted

quoted

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

This change works for me. Ack.

Thanks,
Luke