Re: Re*: Tilde spec - befuzzled

[Luke Diamand <luke@diamand.org>]

On 29/02/12 19:13, Junio C Hamano wrote:
> Andreas Ericsson<ae@op5.se>  writes:
>
>> 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...

This change works for me. Ack.

Thanks,
Luke


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