name for A..B ranges?

> Is there a common name for the A..B range format (two dots) that would
> complement the A...B (three dots) symmetric range format's name?
> 
> I was looking at the --left-right distinctions and noticed that the trail
> back to the symmetric range description was rather thin (it's buried within
> gitrevisions:Specifying Ranges, and even then its called a symmetric
> difference.

> On Wed, Jun 22, 2016 at 08:25:59AM +0100, Philip Oakley wrote:
>
>> Is there a common name for the A..B range format (two dots) that would
>> complement the A...B (three dots) symmetric range format's name?
>> 
>> I was looking at the --left-right distinctions and noticed that the trail
>> back to the symmetric range description was rather thin (it's buried within
>> gitrevisions:Specifying Ranges, and even then its called a symmetric
>> difference.
>
> I would just call it a range, or possibly a set difference. But I don't
> think we have any established naming beyond that.

> Jeff King <peff@peff.net> writes:
>
>> On Wed, Jun 22, 2016 at 08:25:59AM +0100, Philip Oakley wrote:
>>
>>> Is there a common name for the A..B range format (two dots) that would
>>> complement the A...B (three dots) symmetric range format's name?
>>>
>>> I was looking at the --left-right distinctions and noticed that the 
>>> trail
>>> back to the symmetric range description was rather thin (it's buried 
>>> within
>>> gitrevisions:Specifying Ranges, and even then its called a symmetric
>>> difference.
>>
>> I would just call it a range, or possibly a set difference. But I don't
>> think we have any established naming beyond that.
>
> Yup, I think "range" is the commonly used word in discussions here.
> When inventing A...B as a new thing in addition to A..B, we called
> the former "symmetric difference", and what is implied by that is
> the latter is "asymmetric difference"; we do not say that unless we
> are contrasting between the two, though.
>

> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> ---
>  Documentation/revisions.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 131060c..87be9c4 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -246,7 +246,7 @@ The '{caret}' (caret) notation
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>  To exclude commits reachable from a commit, a prefix '{caret}'
>  notation is used.  E.g. '{caret}r1 r2' means commits reachable
> -from 'r2' but exclude the ones reachable from 'r1'.
> +from 'r2' but exclude 'r1' and those reachable from 'r1'.

> Philip Oakley <philipoakley@iee.org> writes:
>
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>>  Documentation/revisions.txt | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
>> index 131060c..87be9c4 100644
>> --- a/Documentation/revisions.txt
>> +++ b/Documentation/revisions.txt
>> @@ -246,7 +246,7 @@ The '{caret}' (caret) notation
>>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>  To exclude commits reachable from a commit, a prefix '{caret}'
>>  notation is used.  E.g. '{caret}r1 r2' means commits reachable
>> -from 'r2' but exclude the ones reachable from 'r1'.
>> +from 'r2' but exclude 'r1' and those reachable from 'r1'.
>
> Well, if you have to spell that out, you'd want to spell out r2 side
> too, no?  That is,

>
> ... means commits 'r2' and those reachable from 'r2', but
> exclude 'r1' and those reachable from 'r1'.
>
> The (sub)document has 16 grep hits of "reach(able)"; a reader who
> needs this clarification would need all of them clarified, but
> repeating "X and those reachable from X" everywhere is not a good
> way to do so.  Perhaps a separate sentence upfront that defines what
> "reachable" means is a better solution, no?
>
> Something like the attached patch may be a good starting point, but
> this leaves two forward-references of reachable in the part that
> describes ways to specify a single object (e.g. find a commit with
> this string that is reachable by X) we may need to address, perhaps
> by adding "(see below)" or something.
>
>
> Documentation/revisions.txt | 4 ++++
> 1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 19314e3..34642b9 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -242,6 +242,10 @@ specifying a single revision with the notation
> described in the
> previous section means the set of commits reachable from that
> commit, following the commit ancestry chain.
>
> +A commit Y is said to be reachable from commit X if Y is X, or if Y
> +is reachable from any any of X's parents.  We also say "Y is an
> +ancestor of X" in such a case.
> +
> To exclude commits reachable from a commit, a prefix '{caret}'
> notation is used.  E.g. '{caret}r1 r2' means commits reachable
> from 'r2' but exclude the ones reachable from 'r1'.
>
> 

>>>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>>  To exclude commits reachable from a commit, a prefix '{caret}'
>>>  notation is used.  E.g. '{caret}r1 r2' means commits reachable
>>> -from 'r2' but exclude the ones reachable from 'r1'.
>>> +from 'r2' but exclude 'r1' and those reachable from 'r1'.
>>
>> Well, if you have to spell that out, you'd want to spell out r2 side
>> too, no?  That is,
>
> The clarification wasn't about what "reachable" means but about inclusivity,
> such as whether 0..4 would give 0,1,2,3,4 or would be 'off by one' and only
> give 1,2,3,4. And in this case it's the latter.

> On Fri, Jul 1, 2016 at 3:08 PM, Philip Oakley <philipoakley@iee.org> wrote:
>>>>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>>>  To exclude commits reachable from a commit, a prefix '{caret}'
>>>>  notation is used.  E.g. '{caret}r1 r2' means commits reachable
>>>> -from 'r2' but exclude the ones reachable from 'r1'.
>>>> +from 'r2' but exclude 'r1' and those reachable from 'r1'.
>>>
>>> Well, if you have to spell that out, you'd want to spell out r2 side
>>> too, no?  That is,
>>
>> The clarification wasn't about what "reachable" means but about inclusivity,
>> such as whether 0..4 would give 0,1,2,3,4 or would be 'off by one' and only
>> give 1,2,3,4. And in this case it's the latter.
>
> Well, you have the same inclusivity issue on the opposite end, no? Is 0..4
> a range with 0,1,2,3,4? 0,1,2,3? 1,2,3,4? or 1,2,3?
>
>> Describing 'reachability' is a whole different kettle of fish, as you
>> highlight below, and would be separate from this patch.
>
> I am not sure I agree. It all is about "is the endpoint included or not?".

> Junio C Hamano <gitster@pobox.com> writes:
>
>> On Fri, Jul 1, 2016 at 3:08 PM, Philip Oakley <philipoakley@iee.org> 
>> wrote:
>>>>>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>>>>  To exclude commits reachable from a commit, a prefix '{caret}'
>>>>>  notation is used.  E.g. '{caret}r1 r2' means commits reachable
>>>>> -from 'r2' but exclude the ones reachable from 'r1'.
>>>>> +from 'r2' but exclude 'r1' and those reachable from 'r1'.

>>>>
>>>> Well, if you have to spell that out, you'd want to spell out r2 side
>>>> too, no?  That is,
>>>
>>> The clarification wasn't about what "reachable" means but about 
>>> inclusivity,
>>> such as whether 0..4 would give 0,1,2,3,4 or would be 'off by one' and 
>>> only
>>> give 1,2,3,4. And in this case it's the latter.
>>
>> Well, you have the same inclusivity issue on the opposite end, no? Is 
>> 0..4
>> a range with 0,1,2,3,4? 0,1,2,3? 1,2,3,4? or 1,2,3?

>>
>> I am not sure I agree. It all is about "is the endpoint included or 
>> not?".
>
> This did not come out as illustrating as I hoped.  Let's put it
> differently.
>
> I think this is all about how "reachable" is defined.  "Am I an
> ancestor of myself?" is the question.

>
> If "all commits reachable from r1" includes 'r1', then, it is clear
> that "... but exclude those reachable from 'r1'" means 'r1' is not
> part of the resulting set.
>
> If I were not an ancestor of me, on the other hand, "... but exclude
> those who are ancestors of 'r1'" would not exclude 'r1'.  If 'r1' is
> reachable from 'r2', then 'r1' would be in the resulting set.
>
> The same thing happens at the opposite end of the "range".  If I am
> an ancestor of me, then "all commits reachable from 'r2'" does
> inculde 'r2'; if I am not an ancestor of me, 'r2' is not part of the
> resulting set.
>

> Note.
> I said "range" in quotes, because this is not like
> drawing a straight line and placing two points to denote the
> lower and the upper bounds of the "range".  What Git does is
> a set operation, "r2 ^r1" excludes what is reachable from r1
>        from the set of commits that are reachable from r2.

>
> By choosing the definition of "reachable" consistently, 0..4 can
> mean either 1,2,3,4 (I am reachable from myself) or 0,1,2,3 (I can
> not be reached by me), and in order to clarify that we give 1,2,3,4
> and not 0,1,2,3, we still need to clearly define what "reachable"
> means.

> This is the re-roll of the po/range-doc (2016-06-27) 3 commits
>
> The order is slightly re-arranged, and an additional patch clarifying
> that ^r1 excludes r1 itself being added.
>
> The heading have been tweaked.

> While there, also break out the other shorthand notations and
> add a title for the revision range summary (which also appears
> in git-rev-parse, so keep it mixed case).
>
> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> ---
>   Documentation/revisions.txt | 23 +++++++++++++++++------
>   1 file changed, 17 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 79f6d03..1c59e87 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -242,35 +242,46 @@ specifying a single revision with the notation described in the
>   previous section means the set of commits reachable from that
>   commit, following the commit ancestry chain.
>
> +The '{caret}' (caret) notation
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>   To exclude commits reachable from a commit, a prefix '{caret}'
>   notation is used.  E.g. '{caret}r1 r2' means commits reachable
>   from 'r2' but exclude the ones reachable from 'r1'.

> +The '{caret}r1 r2' set operation appears so often that there is a shorthand
>   for it.  When you have two commits 'r1' and 'r2' (named according
>   to the syntax explained in SPECIFYING REVISIONS above), you can ask
>   for commits that are reachable from r2 excluding those that are reachable
>   from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
>
> +The '...' (three dot) Symmetric Difference notation
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>   A similar notation 'r1\...r2' is called symmetric difference
>   of 'r1' and 'r2' and is defined as
>   'r1 r2 --not $(git merge-base --all r1 r2)'.
>   It is the set of commits that are reachable from either one of
>   'r1' (Left side) or 'r2' (Right side) but not from both.
>
> -In these two shorthands, you can omit one end and let it default to HEAD.
> +In these two shorthand notations, you can omit one end and let it default to HEAD.
>   For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What
>   did I do since I forked from the origin branch?"  Similarly, '..origin'
>   is a shorthand for 'HEAD..origin' and asks "What did the origin do since
>   I forked from them?"  Note that '..' would mean 'HEAD..HEAD' which is an
>   empty range that is both reachable and unreachable from HEAD.

>
> +Additional '{caret}' Shorthand notations
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>   Two other shorthands for naming a set that is formed by a commit
> -and its parent commits exist.  The 'r1{caret}@' notation means all
> -parents of 'r1'.  'r1{caret}!' includes commit 'r1' but excludes
> -all of its parents.
> +and its parent commits exist.

>
> -To summarize:
> +The 'r1{caret}@' notation means all parents of 'r1'.
> +
> +'r1{caret}!' includes commit 'r1' but excludes all of its parents.
> +
> +Revision Range Summary
> +----------------------

>> +The '{caret}' (caret) notation
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>   To exclude commits reachable from a commit, a prefix '{caret}'
>>   notation is used.  E.g. '{caret}r1 r2' means commits reachable
>>   from 'r2' but exclude the ones reachable from 'r1'.
>
> All of these headings render poorly in the manpage, at least for me
> (Ubuntu 16.04).  Only the first word appears in bold; the '-quoted
> text is not bold but underlined, and the rest of the header is plain.
>
>
> Also, I think calling this "The ^ notation" is confusing, because
> there's already an earlier paragraph on the "<rev>^" syntax.
>
> Maybe we don't need a header here?  I only suggest that because I'm
> having trouble coming up with a nice alternative.  "Commit Exclusion"?

>> -This set operation appears so often that there is a shorthand
>> +The '..' (two-dot) range notation
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> Perhaps "Range notation", to mirror the capitalization of "Symmetric
> Difference" in the next header?
>> ...
>> +The '...' (three dot) Symmetric Difference notation

>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>   A similar notation 'r1\...r2' is called symmetric difference
>>   of 'r1' and 'r2' and is defined as
>>   'r1 r2 --not $(git merge-base --all r1 r2)'.
>>   It is the set of commits that are reachable from either one of
>>   'r1' (Left side) or 'r2' (Right side) but not from both.
>>
>> -In these two shorthands, you can omit one end and let it default to HEAD.
>> +In these two shorthand notations, you can omit one end and let it default to HEAD.
>>   For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What
>>   did I do since I forked from the origin branch?"  Similarly, '..origin'
>>   is a shorthand for 'HEAD..origin' and asks "What did the origin do since
>>   I forked from them?"  Note that '..' would mean 'HEAD..HEAD' which is an
>>   empty range that is both reachable and unreachable from HEAD.
>
> Unfortunately the new headings make it appear that this paragraph is
> exclusively part of the '...' notation section.  Folks reading the
> ..' section are likely to skip it.
>
> I like the examples, though.  I think it would be worthwhile to remove
> this paragraph and fold it explicitly into the '..' and '...' notation
> sections.

> So add something like this to the '..' section (only the first
> sentence here is new):
>
> 	Either r1 or r2 can be omitted, in which case HEAD is used as
> 	the default.  For example, 'origin..' is a shorthand for
> 	'origin..HEAD' and asks "What did I do since I forked from the
> 	origin branch?"  Similarly, '..origin' is a shorthand for
> 	'HEAD..origin' and asks "What did the origin do since I forked
> 	from them?"  Note that '..' would mean 'HEAD..HEAD' which is an
> 	empty range that is both reachable and unreachable from HEAD.
>
> And also, add the same first sentence and a different example to the
> ...' section.  Something like this:
>
> 	Either r1 or r2 can be omitted, in which case HEAD is used as
> 	the default.  For example, 'origin...' is a shorthand for
> 	'origin...HEAD' and asks "What have I and origin both done
> 	since I forked from the origin branch?"  Note that 'origin...'
> 	and '...origin' ask the same question.

>> +Additional '{caret}' Shorthand notations
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>   Two other shorthands for naming a set that is formed by a commit
>> -and its parent commits exist.  The 'r1{caret}@' notation means all
>> -parents of 'r1'.  'r1{caret}!' includes commit 'r1' but excludes
>> -all of its parents.
>> +and its parent commits exist.
>
> I think descriptions of <rev>^@ and <rev>^! should live under the main
> description of <rev>^.  That part already describes the numeric
> suffix, so describing a couple of special suffixes there seems like a
> natural fit.

> Marc Branchaud <marcnarc@xiplink.com> writes:
>
>>> +The '{caret}' (caret) notation
>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>>   To exclude commits reachable from a commit, a prefix '{caret}'
>>>   notation is used.  E.g. '{caret}r1 r2' means commits reachable
>>>   from 'r2' but exclude the ones reachable from 'r1'.
>>
>> All of these headings render poorly in the manpage, at least for me
>> (Ubuntu 16.04).  Only the first word appears in bold; the '-quoted
>> text is not bold but underlined, and the rest of the header is plain.
>>
>>
>> Also, I think calling this "The ^ notation" is confusing, because
>> there's already an earlier paragraph on the "<rev>^" syntax.
>>
>> Maybe we don't need a header here?  I only suggest that because I'm
>> having trouble coming up with a nice alternative.  "Commit Exclusion"?
>
> Thanks for pointing out the potential confusion between ^X (exclude
> reachable), and X^ (the first parent).  Commit exclusion is probably
> a good heading.
>

>>> -This set operation appears so often that there is a shorthand
>>> +The '..' (two-dot) range notation
>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>
>> Perhaps "Range notation", to mirror the capitalization of "Symmetric
>> Difference" in the next header?
>>> ...
>>> +The '...' (three dot) Symmetric Difference notation
>
> This uses a strange capitalization rule.  s/notation/Notation/
> perhaps?  The same comment for "Additional Shothand notation" below.
>

>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>>   A similar notation 'r1\...r2' is called symmetric difference
>>>   of 'r1' and 'r2' and is defined as
>>>   'r1 r2 --not $(git merge-base --all r1 r2)'.
>>>   It is the set of commits that are reachable from either one of
>>>   'r1' (Left side) or 'r2' (Right side) but not from both.
>>>
>>> -In these two shorthands, you can omit one end and let it default to 
>>> HEAD.
>>> +In these two shorthand notations, you can omit one end and let it 
>>> default to HEAD.
>>>   For example, 'origin..' is a shorthand for 'origin..HEAD' and asks 
>>> "What
>>>   did I do since I forked from the origin branch?"  Similarly, 
>>> '..origin'
>>>   is a shorthand for 'HEAD..origin' and asks "What did the origin do 
>>> since
>>>   I forked from them?"  Note that '..' would mean 'HEAD..HEAD' which is 
>>> an
>>>   empty range that is both reachable and unreachable from HEAD.
>>
>> Unfortunately the new headings make it appear that this paragraph is
>> exclusively part of the '...' notation section.  Folks reading the
>> ..' section are likely to skip it.
>>
>> I like the examples, though.  I think it would be worthwhile to remove
>> this paragraph and fold it explicitly into the '..' and '...' notation
>> sections.
>
> An alternative would be to have
>
>    - Dotted range notations
>      - Two-dot notation
>      - Three-dot notation
>
> which would help make it stand out that defaulting is common
> characteristics between .. and ... notations.  But I can imagine
> that your "with slight duplication" variant below would work well,
> too.

>
>> So add something like this to the '..' section (only the first
>> sentence here is new):
>>
>> Either r1 or r2 can be omitted, in which case HEAD is used as
>> the default.  For example, 'origin..' is a shorthand for
>> 'origin..HEAD' and asks "What did I do since I forked from the
>> origin branch?"  Similarly, '..origin' is a shorthand for
>> 'HEAD..origin' and asks "What did the origin do since I forked
>> from them?"  Note that '..' would mean 'HEAD..HEAD' which is an
>> empty range that is both reachable and unreachable from HEAD.
>>
>> And also, add the same first sentence and a different example to the
>> ...' section.  Something like this:
>>
>> Either r1 or r2 can be omitted, in which case HEAD is used as
>> the default.  For example, 'origin...' is a shorthand for
>> 'origin...HEAD' and asks "What have I and origin both done
>> since I forked from the origin branch?"  Note that 'origin...'
>> and '...origin' ask the same question.
>
>>> +Additional '{caret}' Shorthand notations
>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>>   Two other shorthands for naming a set that is formed by a commit
>>> -and its parent commits exist.  The 'r1{caret}@' notation means all
>>> -parents of 'r1'.  'r1{caret}!' includes commit 'r1' but excludes
>>> -all of its parents.
>>> +and its parent commits exist.
>>
>> I think descriptions of <rev>^@ and <rev>^! should live under the main
>> description of <rev>^.  That part already describes the numeric
>> suffix, so describing a couple of special suffixes there seems like a
>> natural fit.
>
> I actually think this is a good place to have them described.
> <rev>^<number> is about specifying a single commit.  These two are
> not that (you can say HEAD^2^@ but you cannot say HEAD^@^2, for
> example).

>> I actually think this is a good place to have them described.
>> <rev>^<number> is about specifying a single commit.  These two are
>> not that (you can say HEAD^2^@ but you cannot say HEAD^@^2, for
>> example).
> 
> These two are special cases I'm not too familiar with, particularly
> the r1^! which I didn't understand from the description...

>W dniu 2016-07-13 o 00:11, Philip Oakley pisze:
>> From: "Junio C Hamano" <gitster@pobox.com>
> [...]
>>> I actually think this is a good place to have them described.
>>> <rev>^<number> is about specifying a single commit.  These two are
>>> not that (you can say HEAD^2^@ but you cannot say HEAD^@^2, for
>>> example).
>>
>> These two are special cases I'm not too familiar with, particularly
>> the r1^! which I didn't understand from the description...
>
> <rev>^@ is all parents of <rev>, that is
>
>  <rev>^@  ==  <rev>^1 <rev>^2 ... <rev>^<n>
>
> where <n> is number of parents commit <rev> has.
>
>
> <rev>^! is (if standalone) a single commit range, only <rev> revision.
> It is actually
>
>  <rev>^!  ==  ( <rev> --not <rev>^@ )
>
> that is, reachable from <rev> but not from any of its parents.
> Parentheses here denote that `--not` does not affect the rest of
> rev-like parameters.
>
>
> Hope that helps
> -- 

> On 2016-07-11 04:25 PM, Philip Oakley wrote:
>> While there, also break out the other shorthand notations and
>> add a title for the revision range summary (which also appears
>> in git-rev-parse, so keep it mixed case).
>>
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>>   Documentation/revisions.txt | 23 +++++++++++++++++------
>>   1 file changed, 17 insertions(+), 6 deletions(-)
>>
>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
>> index 79f6d03..1c59e87 100644
>> --- a/Documentation/revisions.txt
>> +++ b/Documentation/revisions.txt
>> @@ -242,35 +242,46 @@ specifying a single revision with the notation 
>> described in the
>>   previous section means the set of commits reachable from that
>>   commit, following the commit ancestry chain.
>>
>> +The '{caret}' (caret) notation
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>   To exclude commits reachable from a commit, a prefix '{caret}'
>>   notation is used.  E.g. '{caret}r1 r2' means commits reachable
>>   from 'r2' but exclude the ones reachable from 'r1'.
>
> All of these headings render poorly in the manpage, at least for me 
> (Ubuntu 16.04).  Only the first word appears in bold; the '-quoted text is 
> not bold but underlined, and the rest of the header is plain.

>>
>> -This set operation appears so often that there is a shorthand
>> +The '..' (two-dot) range notation
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> Perhaps "Range notation", to mirror the capitalization of "Symmetric 
> Difference" in the next header?

>
>> +The '{caret}r1 r2' set operation appears so often that there is a 
>> shorthand
>>   for it.  When you have two commits 'r1' and 'r2' (named according
>>   to the syntax explained in SPECIFYING REVISIONS above), you can ask
>>   for commits that are reachable from r2 excluding those that are 
>> reachable
>>   from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
>>
>> +The '...' (three dot) Symmetric Difference notation
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>   A similar notation 'r1\...r2' is called symmetric difference
>>   of 'r1' and 'r2' and is defined as
>>   'r1 r2 --not $(git merge-base --all r1 r2)'.
>>   It is the set of commits that are reachable from either one of
>>   'r1' (Left side) or 'r2' (Right side) but not from both.
>>
>> -In these two shorthands, you can omit one end and let it default to 
>> HEAD.
>> +In these two shorthand notations, you can omit one end and let it 
>> default to HEAD.
>>   For example, 'origin..' is a shorthand for 'origin..HEAD' and asks 
>> "What
>>   did I do since I forked from the origin branch?"  Similarly, '..origin'
>>   is a shorthand for 'HEAD..origin' and asks "What did the origin do 
>> since
>>   I forked from them?"  Note that '..' would mean 'HEAD..HEAD' which is 
>> an
>>   empty range that is both reachable and unreachable from HEAD.
>
> Unfortunately the new headings make it appear that this paragraph is 
> exclusively part of the '...' notation section.  Folks reading the '..' 
> section are likely to skip it.

>
> I like the examples, though.  I think it would be worthwhile to remove 
> this paragraph and fold it explicitly into the '..' and '...' notation 
> sections.
>
> So add something like this to the '..' section (only the first sentence 
> here is new):
>
> Either r1 or r2 can be omitted, in which case HEAD is used as
> the default.  For example, 'origin..' is a shorthand for
> 'origin..HEAD' and asks "What did I do since I forked from the
> origin branch?"  Similarly, '..origin' is a shorthand for
> 'HEAD..origin' and asks "What did the origin do since I forked
> from them?"  Note that '..' would mean 'HEAD..HEAD' which is an
> empty range that is both reachable and unreachable from HEAD.
>
> And also, add the same first sentence and a different example to the '...' 
> section.  Something like this:
>
> Either r1 or r2 can be omitted, in which case HEAD is used as
> the default.  For example, 'origin...' is a shorthand for
> 'origin...HEAD' and asks "What have I and origin both done
> since I forked from the origin branch?"  Note that 'origin...'
> and '...origin' ask the same question.
>
>>
>> +Additional '{caret}' Shorthand notations
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>   Two other shorthands for naming a set that is formed by a commit
>> -and its parent commits exist.  The 'r1{caret}@' notation means all
>> -parents of 'r1'.  'r1{caret}!' includes commit 'r1' but excludes
>> -all of its parents.
>> +and its parent commits exist.
>
> I think descriptions of <rev>^@ and <rev>^! should live under the main 
> description of <rev>^.  That part already describes the numeric suffix, so 
> describing a couple of special suffixes there seems like a natural fit.

>
> Two other shorthands exist for naming a set that is formed
> by a commit and its parent commits.
>
>>
>> -To summarize:
>> +The 'r1{caret}@' notation means all parents of 'r1'.
>> +
>> +'r1{caret}!' includes commit 'r1' but excludes all of its parents.
>> +
>> +Revision Range Summary
>> +----------------------
>
> I think this should be a sub-heading (~~~~~~~), not a top-level heading.
>

> > > +The '{caret}' (caret) notation
> > > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > >   To exclude commits reachable from a commit, a prefix '{caret}'
> > >   notation is used.  E.g. '{caret}r1 r2' means commits reachable
> > >   from 'r2' but exclude the ones reachable from 'r1'.
> > 
> > All of these headings render poorly in the manpage, at least for me
> > (Ubuntu 16.04).  Only the first word appears in bold; the '-quoted text
> > is not bold but underlined, and the rest of the header is plain.
> 
> Which doc package is that with? It had formatted OK for the html web pages.

> Do not self-define `reachable`, which can lead to misunderstanding.
> Instead define `reachability` explictly.
>
> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> ---
>   Documentation/revisions.txt | 14 ++++++++++----
>   1 file changed, 10 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 1c59e87..a3cd28b 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -237,10 +237,16 @@ SPECIFYING RANGES
>   -----------------
>
>   History traversing commands such as `git log` operate on a set
> -of commits, not just a single commit.  To these commands,
> -specifying a single revision with the notation described in the
> -previous section means the set of commits reachable from that
> -commit, following the commit ancestry chain.
> +of commits, not just a single commit.
> +
> +For these commands,
> +specifying a single revision, using the notation described in the
> +previous section, means the `reachable` set of commits of the given
> +commit.

> On 2016-07-11 04:25 PM, Philip Oakley wrote:
>> Do not self-define `reachable`, which can lead to misunderstanding.
>> Instead define `reachability` explictly.
>>
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>>   Documentation/revisions.txt | 14 ++++++++++----
>>   1 file changed, 10 insertions(+), 4 deletions(-)
>>
>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
>> index 1c59e87..a3cd28b 100644
>> --- a/Documentation/revisions.txt
>> +++ b/Documentation/revisions.txt
>> @@ -237,10 +237,16 @@ SPECIFYING RANGES
>>   -----------------
>>
>>   History traversing commands such as `git log` operate on a set
>> -of commits, not just a single commit.  To these commands,
>> -specifying a single revision with the notation described in the
>> -previous section means the set of commits reachable from that
>> -commit, following the commit ancestry chain.
>> +of commits, not just a single commit.
>> +
>> +For these commands,
>> +specifying a single revision, using the notation described in the
>> +previous section, means the `reachable` set of commits of the given
>> +commit.
>
> Better as "... means the set of commits `reachable` from the given 
> commit."

>
>> +
>> +A commit's reachable set is the commit itself and the commits of
>> +its ancestry chain.
>> +
>
> s/of/in/

>  Documentation/revisions.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 19314e3..79f6d03 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -256,7 +256,7 @@ A similar notation 'r1\...r2' is called symmetric difference
>  of 'r1' and 'r2' and is defined as
>  'r1 r2 --not $(git merge-base --all r1 r2)'.
>  It is the set of commits that are reachable from either one of
> -'r1' or 'r2' but not from both.
> +'r1' (Left side) or 'r2' (Right side) but not from both.

> Philip Oakley <philipoakley@iee.org> writes:
>
>> The terms Left and Right side originate from the symmetric
>> difference. Name them there.
>> ---
>
> Sign-off?

>
>>  Documentation/revisions.txt | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
>> index 19314e3..79f6d03 100644
>> --- a/Documentation/revisions.txt
>> +++ b/Documentation/revisions.txt
>> @@ -256,7 +256,7 @@ A similar notation 'r1\...r2' is called symmetric 
>> difference
>>  of 'r1' and 'r2' and is defined as
>>  'r1 r2 --not $(git merge-base --all r1 r2)'.
>>  It is the set of commits that are reachable from either one of
>> -'r1' or 'r2' but not from both.
>> +'r1' (Left side) or 'r2' (Right side) but not from both.
>
> I think it is a good idea to call them explicitly left and right,
> but I do not think they need to be capitalized here or on the title
> of the patch.

>
>>  In these two shorthands, you can omit one end and let it default to 
>> HEAD.
>>  For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What
>

> This is the re-roll of the po/range-doc (2016-07-01) 3 commits and its
> follow on patch.
>
> The series has gained additional patches following the discussions
> ($gmane/298790).
>
> The original first 3 patches are unchanged, though 2/8 has been inserted
> to name the Left and Right ranges.
>
> The extra four patches carefully tease out the clarification of
> reachability. Reachability is defined relative the ancestry chain thus
> (hopefully) avoiding misunderstandings.
>
> The final patch updates the summary examples, and the tricky (for the
> untutored reader) two dots case of a linear development where r1..r2
> excludes r1 itself.
>
> The patches can be squashed together if required.

> Philip Oakley <philipoakley@iee.org> writes:
> 
>> This is the re-roll of the po/range-doc (2016-07-01) 3 commits and its
>> follow on patch.
>>
>> The series has gained additional patches following the discussions
>> ($gmane/298790).

>>
>> The patches can be squashed together if required.
> 
> Looked mostly sensible, except for a few things mentioned in the
> reviews by Marc (to which I mostly agree with).
> 

> While there, also break out the other shorthand notations and
> add a title for the revision range summary (which also appears
> in git-rev-parse, so keep it mixed case).
>
> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> ---
>   Documentation/revisions.txt | 58 ++++++++++++++++++++++++++++-----------------
>   1 file changed, 36 insertions(+), 22 deletions(-)
>
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 6e9cd41..5b37283 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -242,35 +242,49 @@ specifying a single revision with the notation described in the
>   previous section means the set of commits reachable from that
>   commit, following the commit ancestry chain.
>
> -To exclude commits reachable from a commit, a prefix '{caret}'
> -notation is used.  E.g. '{caret}r1 r2' means commits reachable
> -from 'r2' but exclude the ones reachable from 'r1'.
> -
> -This set operation appears so often that there is a shorthand
> -for it.  When you have two commits 'r1' and 'r2' (named according
> -to the syntax explained in SPECIFYING REVISIONS above), you can ask
> -for commits that are reachable from r2 excluding those that are reachable
> -from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
> -
> -A similar notation 'r1\...r2' is called symmetric difference
> -of 'r1' and 'r2' and is defined as
> -'r1 r2 --not $(git merge-base --all r1 r2)'.
> -It is the set of commits that are reachable from either one of
> -'r1' (left side) or 'r2' (right side) but not from both.
> -
> -In these two shorthands, you can omit one end and let it default to HEAD.
> +Commit Exclusions
> +~~~~~~~~~~~~~~~~~
> +
> +'{caret}<rev>' (caret) Notation::
> + To exclude commits reachable from a commit, a prefix '{caret}'
> + notation is used.  E.g. '{caret}r1 r2' means commits reachable
> + from 'r2' but exclude the ones reachable from 'r1'.
> +
> +Dotted Range Notations
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +The '..' (two-dot) Range Notation::
> + The '{caret}r1 r2' set operation appears so often that there is a shorthand
> + for it.  When you have two commits 'r1' and 'r2' (named according
> + to the syntax explained in SPECIFYING REVISIONS above), you can ask
> + for commits that are reachable from r2 excluding those that are reachable
> + from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
> +
> +The '...' (three dot) Symmetric Difference Notation::
> + A similar notation 'r1\...r2' is called symmetric difference

> + of 'r1' and 'r2' and is defined as
> + 'r1 r2 --not $(git merge-base --all r1 r2)'.
> + It is the set of commits that are reachable from either one of
> + 'r1' (left side) or 'r2' (right side) but not from both.
> +
> +In these two shorthand notations, you can omit one end and let it default to HEAD.
>   For example, 'origin..' is a shorthand for 'origin..HEAD' and asks "What
>   did I do since I forked from the origin branch?"  Similarly, '..origin'
>   is a shorthand for 'HEAD..origin' and asks "What did the origin do since
>   I forked from them?"  Note that '..' would mean 'HEAD..HEAD' which is an
>   empty range that is both reachable and unreachable from HEAD.
>
> -Two other shorthands for naming a set that is formed by a commit
> -and its parent commits exist.  The 'r1{caret}@' notation means all
> -parents of 'r1'.  'r1{caret}!' includes commit 'r1' but excludes
> -all of its parents.
> +Special '<rev>{caret}' Shorthand Notations
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

> +Two other shorthands exist, particularly useful for merge commits, is
> +for naming a set that is formed by a commit and its parent commits.
>
> -To summarize:
> +The 'r1{caret}@' notation means all parents of 'r1'.
> +
> +'r1{caret}!' includes commit 'r1' but excludes all of its parents.

> On 2016-07-20 05:10 PM, Philip Oakley wrote:
>> While there, also break out the other shorthand notations and
>> add a title for the revision range summary (which also appears
>> in git-rev-parse, so keep it mixed case).
>>
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>>   Documentation/revisions.txt | 58 
>> ++++++++++++++++++++++++++++-----------------
>>   1 file changed, 36 insertions(+), 22 deletions(-)
>>
>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
>> index 6e9cd41..5b37283 100644
>> --- a/Documentation/revisions.txt
>> +++ b/Documentation/revisions.txt
>> @@ -242,35 +242,49 @@ specifying a single revision with the notation 
>> described in the
>>   previous section means the set of commits reachable from that
>>   commit, following the commit ancestry chain.
>>
>> -To exclude commits reachable from a commit, a prefix '{caret}'
>> -notation is used.  E.g. '{caret}r1 r2' means commits reachable
>> -from 'r2' but exclude the ones reachable from 'r1'.
>> -
>> -This set operation appears so often that there is a shorthand
>> -for it.  When you have two commits 'r1' and 'r2' (named according
>> -to the syntax explained in SPECIFYING REVISIONS above), you can ask
>> -for commits that are reachable from r2 excluding those that are 
>> reachable
>> -from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
>> -
>> -A similar notation 'r1\...r2' is called symmetric difference
>> -of 'r1' and 'r2' and is defined as
>> -'r1 r2 --not $(git merge-base --all r1 r2)'.
>> -It is the set of commits that are reachable from either one of
>> -'r1' (left side) or 'r2' (right side) but not from both.
>> -
>> -In these two shorthands, you can omit one end and let it default to 
>> HEAD.
>> +Commit Exclusions
>> +~~~~~~~~~~~~~~~~~
>> +
>> +'{caret}<rev>' (caret) Notation::
>> + To exclude commits reachable from a commit, a prefix '{caret}'
>> + notation is used.  E.g. '{caret}r1 r2' means commits reachable
>> + from 'r2' but exclude the ones reachable from 'r1'.
>> +
>> +Dotted Range Notations
>> +~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +The '..' (two-dot) Range Notation::
>> + The '{caret}r1 r2' set operation appears so often that there is a 
>> shorthand
>> + for it.  When you have two commits 'r1' and 'r2' (named according
>> + to the syntax explained in SPECIFYING REVISIONS above), you can ask
>> + for commits that are reachable from r2 excluding those that are 
>> reachable
>> + from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
>> +
>> +The '...' (three dot) Symmetric Difference Notation::
>> + A similar notation 'r1\...r2' is called symmetric difference
>
> s/called/called the/

>
>> + of 'r1' and 'r2' and is defined as
>> + 'r1 r2 --not $(git merge-base --all r1 r2)'.
>> + It is the set of commits that are reachable from either one of
>> + 'r1' (left side) or 'r2' (right side) but not from both.
>> +
>> +In these two shorthand notations, you can omit one end and let it 
>> default to HEAD.
>>   For example, 'origin..' is a shorthand for 'origin..HEAD' and asks 
>> "What
>>   did I do since I forked from the origin branch?"  Similarly, '..origin'
>>   is a shorthand for 'HEAD..origin' and asks "What did the origin do 
>> since
>>   I forked from them?"  Note that '..' would mean 'HEAD..HEAD' which is 
>> an
>>   empty range that is both reachable and unreachable from HEAD.
>>
>> -Two other shorthands for naming a set that is formed by a commit
>> -and its parent commits exist.  The 'r1{caret}@' notation means all
>> -parents of 'r1'.  'r1{caret}!' includes commit 'r1' but excludes
>> -all of its parents.
>> +Special '<rev>{caret}' Shorthand Notations
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> Sorry, but this header also does not render properly in the man page. 
> Maybe just "Special {caret} Shorthand Notations"?  (But read on!)

>
>> +Two other shorthands exist, particularly useful for merge commits, is
>> +for naming a set that is formed by a commit and its parent commits.
>>
>> -To summarize:
>> +The 'r1{caret}@' notation means all parents of 'r1'.
>> +
>> +'r1{caret}!' includes commit 'r1' but excludes all of its parents.
>
> My immediate thought upon reading this is "Why not just use 'r1'?"  I 
> think the answer is "This truncates the range."  So, for example, "git log 
> r1" shows you r1 and its ancestors, while "git log r1^!" only shows you 
> r1.  I think you should add this example, or something similar.
>

>
> That makes this "Special Notations" section rather thin.  I suggest moving 
> a slightly expanded <rev>^@ description to a small subsection just before 
> Commit Exclusions, and deleting the Special Notations section altogether. 
> So add something like this:
>
> Commit Parents
> ~~~~~~~~~~~~~~

>
> '<rev>{caret}@' Notation::
> The 'r1{caret}@' notation means all parents of 'r1',
> excluding 'r1' itself.
>
> This smoothly re-introduces the notion of parents for readers who skipped 
> to this section, and helps them make sense of the <rev>^! notation.
>
> Plus there's no longer anything "special" about any of the syntax.
>
>> +
>> +Revision Range Summary
>> +----------------------
>
> Sorry, but the man page renders this in all caps.  I really think you 
> should use ~~~~~~~~~ here.

> From: "Marc Branchaud" <marcnarc@xiplink.com>
>> On 2016-07-20 05:10 PM, Philip Oakley wrote:
>>> While there, also break out the other shorthand notations and
>>> add a title for the revision range summary (which also appears
>>> in git-rev-parse, so keep it mixed case).
>>>
>>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>>> ---
>>>   Documentation/revisions.txt | 58
>>> ++++++++++++++++++++++++++++-----------------
>>>   1 file changed, 36 insertions(+), 22 deletions(-)
>>>
>>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
>>> index 6e9cd41..5b37283 100644
>>> --- a/Documentation/revisions.txt
>>> +++ b/Documentation/revisions.txt
>>> @@ -242,35 +242,49 @@ specifying a single revision with the notation
>>> described in the
>>>   previous section means the set of commits reachable from that
>>>   commit, following the commit ancestry chain.
>>>
>>> -To exclude commits reachable from a commit, a prefix '{caret}'
>>> -notation is used.  E.g. '{caret}r1 r2' means commits reachable
>>> -from 'r2' but exclude the ones reachable from 'r1'.
>>> -
>>> -This set operation appears so often that there is a shorthand
>>> -for it.  When you have two commits 'r1' and 'r2' (named according
>>> -to the syntax explained in SPECIFYING REVISIONS above), you can ask
>>> -for commits that are reachable from r2 excluding those that are
>>> reachable
>>> -from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
>>> -
>>> -A similar notation 'r1\...r2' is called symmetric difference
>>> -of 'r1' and 'r2' and is defined as
>>> -'r1 r2 --not $(git merge-base --all r1 r2)'.
>>> -It is the set of commits that are reachable from either one of
>>> -'r1' (left side) or 'r2' (right side) but not from both.
>>> -
>>> -In these two shorthands, you can omit one end and let it default to
>>> HEAD.
>>> +Commit Exclusions
>>> +~~~~~~~~~~~~~~~~~
>>> +
>>> +'{caret}<rev>' (caret) Notation::
>>> + To exclude commits reachable from a commit, a prefix '{caret}'
>>> + notation is used.  E.g. '{caret}r1 r2' means commits reachable
>>> + from 'r2' but exclude the ones reachable from 'r1'.
>>> +
>>> +Dotted Range Notations
>>> +~~~~~~~~~~~~~~~~~~~~~~
>>> +
>>> +The '..' (two-dot) Range Notation::
>>> + The '{caret}r1 r2' set operation appears so often that there is a
>>> shorthand
>>> + for it.  When you have two commits 'r1' and 'r2' (named according
>>> + to the syntax explained in SPECIFYING REVISIONS above), you can ask
>>> + for commits that are reachable from r2 excluding those that are
>>> reachable
>>> + from r1 by '{caret}r1 r2' and it can be written as 'r1..r2'.
>>> +
>>> +The '...' (three dot) Symmetric Difference Notation::
>>> + A similar notation 'r1\...r2' is called symmetric difference
>>
>> s/called/called the/
>
> The wording is the original ;-) Can change.
>
>>
>>> + of 'r1' and 'r2' and is defined as
>>> + 'r1 r2 --not $(git merge-base --all r1 r2)'.
>>> + It is the set of commits that are reachable from either one of
>>> + 'r1' (left side) or 'r2' (right side) but not from both.
>>> +
>>> +In these two shorthand notations, you can omit one end and let it
>>> default to HEAD.
>>>   For example, 'origin..' is a shorthand for 'origin..HEAD' and asks
>>> "What
>>>   did I do since I forked from the origin branch?"  Similarly,
>>> '..origin'
>>>   is a shorthand for 'HEAD..origin' and asks "What did the origin do
>>> since
>>>   I forked from them?"  Note that '..' would mean 'HEAD..HEAD' which
>>> is an
>>>   empty range that is both reachable and unreachable from HEAD.
>>>
>>> -Two other shorthands for naming a set that is formed by a commit
>>> -and its parent commits exist.  The 'r1{caret}@' notation means all
>>> -parents of 'r1'.  'r1{caret}!' includes commit 'r1' but excludes
>>> -all of its parents.
>>> +Special '<rev>{caret}' Shorthand Notations
>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>
>> Sorry, but this header also does not render properly in the man page.
>> Maybe just "Special {caret} Shorthand Notations"?  (But read on!)
>
> rendered fine on the MYS2 man invocation - I had had to add the <rev>
> prefix to the quoted title to make it work.
>
> What went wrong for you? (I'll read on)

>>
>>> +Two other shorthands exist, particularly useful for merge commits, is
>>> +for naming a set that is formed by a commit and its parent commits.
>>>
>>> -To summarize:
>>> +The 'r1{caret}@' notation means all parents of 'r1'.
>>> +
>>> +'r1{caret}!' includes commit 'r1' but excludes all of its parents.
>>
>> My immediate thought upon reading this is "Why not just use 'r1'?"  I
>> think the answer is "This truncates the range."  So, for example, "git
>> log r1" shows you r1 and its ancestors, while "git log r1^!" only
>> shows you r1.  I think you should add this example, or something similar.
>>
>
> I'd also asked that question in one of my replies earlier $gmane/299849.
> I was then able to determine that it was a width wide 'range' covering
> multi-parent situations.

> $ git rev-parse 6c71a849^!
>> But, really, this means that the notation is another "Commit
>> Exclusion" and properly belongs in that section.
>
> I think it's bigger than that.
>>
>> That makes this "Special Notations" section rather thin.  I suggest
>> moving a slightly expanded <rev>^@ description to a small subsection
>> just before Commit Exclusions, and deleting the Special Notations
>> section altogether. So add something like this:
>>
>> Commit Parents
>> ~~~~~~~~~~~~~~
>
> It's a bit better, but I'm still not sure it really tells the story,
> maybe "Handling Commit Parent(s)", with that subtle extra emphasis!

>>
>> '<rev>{caret}@' Notation::
>> The 'r1{caret}@' notation means all parents of 'r1',
>> excluding 'r1' itself.
>>
>> This smoothly re-introduces the notion of parents for readers who
>> skipped to this section, and helps them make sense of the <rev>^!
>> notation.
>>
>> Plus there's no longer anything "special" about any of the syntax.
>>
>>> +
>>> +Revision Range Summary
>>> +----------------------
>>
>> Sorry, but the man page renders this in all caps.  I really think you
>> should use ~~~~~~~~~ here.
>
> Yes, the man page formating is annoying relative to the web page
> formatting which it has to be compared against.
>
> I felt that it was at a higher level than the other sub-headings, and
> that using mixed case did work well on the html (the Git for Windows
> standard).

> -To summarize:
> +The 'r1{caret}@' notation means all parents of 'r1'.
> +
> +'r1{caret}!' includes commit 'r1' but excludes all of its parents.
> +
> +Revision Range Summary
> +----------------------
>  
>  '<rev>'::
>  	Include commits that are reachable from (i.e. ancestors of)

> No change in the number of patches. Interdiff below.
>
> The patches carefully tease out the clarification of
> reachability. Reachability is defined relative the ancestry chain thus
> (hopefully) avoiding misunderstandings.
>
> The final patch updates the summary examples, and the tricky (for the
> untutored reader) two dots case of a linear development where r1..r2
> excludes r1 itself.

> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
> index 4f009d4..6dc0bb0 100644
> --- a/Documentation/rev-list-options.txt
> +++ b/Documentation/rev-list-options.txt
> @@ -225,7 +225,7 @@ excluded from the output.
>  
>  --left-only::
>  --right-only::
> -	List only commits on the respective side of a symmetric range,
> +	List only commits on the respective side of a symmetric difference,
>  	i.e. only those which would be marked `<` resp. `>` by
>  	`--left-right`.
>  +
> @@ -766,7 +766,7 @@ ifdef::git-rev-list[]
>  endif::git-rev-list[]
>  
>  --left-right::
> -	Mark which side of a symmetric diff a commit is reachable from.
> +	Mark which side of a symmetric difference a commit is reachable from.
>  	Commits from the left side are prefixed with `<` and those from
>  	the right with `>`.  If combined with `--boundary`, those
>  	commits are prefixed with `-`.

>>  --left-right::
>> -	Mark which side of a symmetric diff a commit is reachable from.
>> +	Mark which side of a symmetric difference a commit is reachable from.
>>  	Commits from the left side are prefixed with `<` and those from
>>  	the right with `>`.  If combined with `--boundary`, those
>>  	commits are prefixed with `-`.
>
> That's very nice that two^W three related options, namely --left-only,
> --right-only and --left-right now use the same notation.
>
> I guess that "symmetric range" was to mean "symmetric difference range".

> This has grown like topsy from a little two patch series that tried to
> name the 2-dots notation [1] into this extended set of tweaks.
>
> As documentation can be rather personal, I've split out each small change
> so each can be individually justified.
>
> Since V4, I've confirmed that the format breaking issue is that we cannot
> quote code in headings in the man page layout - ultimately it's a docbook
> decision, and follows the line of analysis Peff identified (see commentary
> in the patch).
>
> In addition the multi-parent notations have been clarified and extended.
>
> Thus the old patch 4 has been split into three. The first three patches 
> are
> unchanged. The following 4 patches are also unchanged.
>
> Finally, at the end an extra 2 patches are added to build up the examples 
> by
> including details of the notation expansions.
>
> This updates po/range-doc (2016-07-20) 8 commits.
>
> Hopefully my updated workflow will get the right patches to the right 
> people.
>
> [1] 
> https://public-inbox.org/git/0648000B273C412AB7140AE959EBC99A%40PhilipOakley/
>
> Philip Oakley (12):
>  doc: use 'symmetric difference' consistently
>  doc: revisions - name the left and right sides
>  doc: show the actual left, right, and boundary marks
>  doc: revisions: give headings for the two and three dot notations
>  doc: revisions: extra clarification of <rev>^! notation effects
>  doc: revisions: single vs multi-parent notation comparison
>  doc: gitrevisions - use 'reachable' in page description
>  doc: gitrevisions - clarify 'latter case' is revision walk
>  doc: revisions  - define `reachable`
>  doc: revisions - clarify reachability examples
>  doc: revisions: show revision expansion in examples
>  doc: revisions: sort examples and fix alignment of the unchanged
>
> Documentation/gitk.txt             |   2 +-
> Documentation/gitrevisions.txt     |   6 +-
> Documentation/pretty-formats.txt   |   2 +-
> Documentation/rev-list-options.txt |   4 +-
> Documentation/revisions.txt        | 121 
> +++++++++++++++++++++++--------------
> 5 files changed, 84 insertions(+), 51 deletions(-)
>
> -- 
> 2.9.0.windows.1
>
>
> 

> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -284,6 +284,10 @@ The 'r1{caret}@' notation means all parents of 'r1'.
>  The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.
>  By itself, this notation denotes the single commit 'r1'.
>  
> +While '<rev>{caret}<n>' was about specifying a single commit parent, these
> +two notations consider all its parents. For example you can say
> +'HEAD{caret}2{caret}@', however you cannot say 'HEAD{caret}@{caret}2'.
> +

> W dniu 13.08.2016 o 01:45, Philip Oakley pisze:
>
>> +'HEAD{caret}2{caret}@', however you cannot say 'HEAD{caret}@{caret}2'.
>
> Though I do wonder if it is implementation limitation, or if it is something
> inherent in the notation, namely that <rev>^@ and <rev>^! resolve (the former
> at least in general, though not for every <rev>) to more than one revision
> specifier.

> Philip Oakley (12):
>   doc: use 'symmetric difference' consistently
>   doc: revisions - name the left and right sides
>   doc: show the actual left, right, and boundary marks
>   doc: revisions: give headings for the two and three dot notations
>   doc: revisions: extra clarification of <rev>^! notation effects
>   doc: revisions: single vs multi-parent notation comparison
>   doc: gitrevisions - use 'reachable' in page description
>   doc: gitrevisions - clarify 'latter case' is revision walk
>   doc: revisions  - define `reachable`
>   doc: revisions - clarify reachability examples
>   doc: revisions: show revision expansion in examples
>   doc: revisions: sort examples and fix alignment of the unchanged
>
>  Documentation/gitk.txt             |   2 +-
>  Documentation/gitrevisions.txt     |   6 +-
>  Documentation/pretty-formats.txt   |   2 +-
>  Documentation/rev-list-options.txt |   4 +-
>  Documentation/revisions.txt        | 125 ++++++++++++++++++++++++-------------
>  5 files changed, 88 insertions(+), 51 deletions(-)
>

> On 2016-08-12 07:45 PM, Philip Oakley wrote:
>> These are the quick fixes to Marc's comments to patches 5,6,11,
>> and a consequential change to 12.
>>
>> Only the changed patches are included.
>
> Looks good to me -- no further comments!
>
> However, I still don't understand why git says 11/12 has "indent with 
> spaces" problems.

>
> M.
>
>
>> Philip Oakley (12):
>>   doc: use 'symmetric difference' consistently
>>   doc: revisions - name the left and right sides
>>   doc: show the actual left, right, and boundary marks
>>   doc: revisions: give headings for the two and three dot notations
>>   doc: revisions: extra clarification of <rev>^! notation effects
>>   doc: revisions: single vs multi-parent notation comparison
>>   doc: gitrevisions - use 'reachable' in page description
>>   doc: gitrevisions - clarify 'latter case' is revision walk
>>   doc: revisions  - define `reachable`
>>   doc: revisions - clarify reachability examples
>>   doc: revisions: show revision expansion in examples
>>   doc: revisions: sort examples and fix alignment of the unchanged
>>
>>  Documentation/gitk.txt             |   2 +-
>>  Documentation/gitrevisions.txt     |   6 +-
>>  Documentation/pretty-formats.txt   |   2 +-
>>  Documentation/rev-list-options.txt |   4 +-
>>  Documentation/revisions.txt        | 125 
>> ++++++++++++++++++++++++-------------
>>  5 files changed, 88 insertions(+), 51 deletions(-)

> From: "Marc Branchaud" <marcnarc@xiplink.com>
>> On 2016-08-12 07:45 PM, Philip Oakley wrote:
>>> These are the quick fixes to Marc's comments to patches 5,6,11,
>>> and a consequential change to 12.
>>>
>>> Only the changed patches are included.
>>
>> Looks good to me -- no further comments!
>>
>> However, I still don't understand why git says 11/12 has "indent with
>> spaces" problems.
>
> I'm guessing it's that the text is monospaced rather than tabbed, and
> it's flagging that.
>
> I'd noticed that it was highlighted in the Git gui (which I use to
> visualise both the diff, the message and the part after the three dashes
> at the same time).

> On 2016-08-15 11:00 AM, Philip Oakley wrote:
>> From: "Marc Branchaud" <marcnarc@xiplink.com>
>>> On 2016-08-12 07:45 PM, Philip Oakley wrote:
>>>> These are the quick fixes to Marc's comments to patches 5,6,11,
>>>> and a consequential change to 12.
>>>>
>>>> Only the changed patches are included.
>>>
>>> Looks good to me -- no further comments!
>>>
>>> However, I still don't understand why git says 11/12 has "indent with
>>> spaces" problems.
>>
>> I'm guessing it's that the text is monospaced rather than tabbed, and
>> it's flagging that.
>>
>> I'd noticed that it was highlighted in the Git gui (which I use to
>> visualise both the diff, the message and the part after the three dashes
>> at the same time).
>
> Actually, it looks like an indent-with-non-tab problem, which is
> supposed to be off by default.
>
> Git doesn't complain about the patch if I set
>     core.whitespace = tabwidth=11
> presumably because the patch uses 10 spaces to indent the offending lines.
>
> But explicitly disabling that check with
>     core.whitespace = -indent-with-non-tab
> doesn't work.
>
> Unfortunately, I don't have time today to track this down.

> On 2016-08-12 07:45 PM, Philip Oakley wrote:
>> These are the quick fixes to Marc's comments to patches 5,6,11,
>> and a consequential change to 12.
>>
>> Only the changed patches are included.
>
> Looks good to me -- no further comments!
>
> However, I still don't understand why git says 11/12 has "indent with
> spaces" problems.

>  History traversing commands such as `git log` operate on a set
> -of commits, not just a single commit.  To these commands,
> -specifying a single revision with the notation described in the
> -previous section means the set of commits reachable from that
> -commit, following the commit ancestry chain.
> +of commits, not just a single commit.
> +
> +For these commands,
> +specifying a single revision, using the notation described in the
> +previous section, means the set of commits `reachable` from the given
> +commit.

>W dniu 12.08.2016 o 09:07, Philip Oakley pisze:
> [...]
>
>>  History traversing commands such as `git log` operate on a set
>> -of commits, not just a single commit.  To these commands,
>> -specifying a single revision with the notation described in the
>> -previous section means the set of commits reachable from that
>> -commit, following the commit ancestry chain.
>> +of commits, not just a single commit.
>> +
>> +For these commands,
>> +specifying a single revision, using the notation described in the
>> +previous section, means the set of commits `reachable` from the given
>> +commit.
>
> Why such strange formatting?  Is it to keep original contents
> for better blame / word diff?

>
>> +
>> +A commit's reachable set is the commit itself and the commits in
>> +its ancestry chain.
>> +
>
> It is all right, but perhaps it would be better to just repeat:
>
>  +Set of commits reachable from given commit is the commit itself
>  +and all the commits in its ancestry chain.

>
> -- 
> Jakub Narębski
>
> 

>>> +
>>> +A commit's reachable set is the commit itself and the commits in
>>> +its ancestry chain.
>>> +
>>
>> It is all right, but perhaps it would be better to just repeat:
>>
>>  +Set of commits reachable from given commit is the commit itself
>>  +and all the commits in its ancestry chain.
> 
> It's very easy to go around in circles here. The original issue was
> the A..B notation for the case where A is a direct descendant of B,
> such that new users, or users more familiar with range notations from
> elsewhere, would expect that the A..B range is *inclusive*, rather
> than an open / closed interval. It was the addressing of that problem
> that lead to the updating of the 'reachability' definition.

>W dniu 29.08.2016 o 15:21, Philip Oakley pisze:
>> From: "Jakub Narębski" <jnareb@gmail.com>
>> Sent: Sunday, August 28, 2016 2:01 PM
>>> W dniu 12.08.2016 o 09:07, Philip Oakley pisze:
> [...]
>
>>>> +For these commands,
>>>> +specifying a single revision, using the notation described in the
>>>> +previous section, means the set of commits `reachable` from the given
>>>> +commit.
> [...]
>>>> +
>>>> +A commit's reachable set is the commit itself and the commits in
>>>> +its ancestry chain.
>>>> +
>>>
>>> It is all right, but perhaps it would be better to just repeat:
>>>
>>>  +Set of commits reachable from given commit is the commit itself
>>>  +and all the commits in its ancestry chain.
>>
>> It's very easy to go around in circles here. The original issue was
>> the A..B notation for the case where A is a direct descendant of B,
>> such that new users, or users more familiar with range notations from
>> elsewhere, would expect that the A..B range is *inclusive*, rather
>> than an open / closed interval. It was the addressing of that problem
>> that lead to the updating of the 'reachability' definition.
>
> All right, I can see that.  It is a worthwhile goal.
>
>> The main part of my sentence formation was to make the 'reachable'
>> part the defining element, rather than being a feature of the set.
>> Maybe it's using the 'set' viewpoint that is distracting?>>
>
> One one hand, the "A commit's reachable set is ..." approach puts
> 'reachable' upfront.  On the other hand it introduces new terminology,
> namely 'reachable set' (or 'reachable set of a commit' to be more
> exact)...  it doesn't read that well to me, but I am not a native
> speaker.
>
> But as I wrote, this is quite all right anyway
> -- 
> Jakub Narębski

> The revisions examples show the revison arguments and the selected
> commits, but do not show the intermediate step of the expansion of
> the special 'range' notations. Extend the examples, including an
> all-parents multi-parent merge commit example.
>
> Sort the examples and fix the alignment for those unaffected
> in the next commit.
>
> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> ---
> new
> Cc: Jakub Narębski <jnareb@gmail.com>
> ---
>  Documentation/revisions.txt | 19 +++++++++++++------
>  1 file changed, 13 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 70864d5..ac7dd8e 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -326,16 +326,23 @@ Revision Range Summary
>    as giving commit '<rev>' and then all its parents prefixed with
>    '{caret}' to exclude them (and their ancestors).
>
> -Here are a handful of examples:
> +Here are a handful of examples using the Loeliger illustration above:
>
> +   Args   Expansion       Selection

>     D                G H D
>     D F              G H I J D F
>     ^G D             H D
>     ^D B             E I J F B
> -   B..C             C
> -   B...C            G H D E B C
> +   B..C   = ^B C          C
> +   B...C  = B ^F C        G H D E B C
>     ^D B C           E I J F B C
>     C                I J F C
> -   C^@              I J F
> -   C^!              C
> -   F^! D            G H D F
> +   C^@    = C^1

> On 2016-08-12 03:07 AM, Philip Oakley wrote:
>> The revisions examples show the revison arguments and the selected
>> commits, but do not show the intermediate step of the expansion of
>> the special 'range' notations. Extend the examples, including an
>> all-parents multi-parent merge commit example.
>>
>> Sort the examples and fix the alignment for those unaffected
>> in the next commit.
>>
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>> new
>> Cc: Jakub Narębski <jnareb@gmail.com>
>> ---
>>  Documentation/revisions.txt | 19 +++++++++++++------
>>  1 file changed, 13 insertions(+), 6 deletions(-)
>>
>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
>> index 70864d5..ac7dd8e 100644
>> --- a/Documentation/revisions.txt
>> +++ b/Documentation/revisions.txt
>> @@ -326,16 +326,23 @@ Revision Range Summary
>>    as giving commit '<rev>' and then all its parents prefixed with
>>    '{caret}' to exclude them (and their ancestors).
>>
>> -Here are a handful of examples:
>> +Here are a handful of examples using the Loeliger illustration above:
>>
>> +   Args   Expansion       Selection
>
> I think "Result" would be better than "Selection" here.

>
>>     D                G H D
>>     D F              G H I J D F
>>     ^G D             H D
>>     ^D B             E I J F B
>> -   B..C             C
>> -   B...C            G H D E B C
>> +   B..C   = ^B C          C
>> +   B...C  = B ^F C        G H D E B C
>>     ^D B C           E I J F B C
>>     C                I J F C
>> -   C^@              I J F
>> -   C^!              C
>> -   F^! D            G H D F
>> +   C^@    = C^1
>
> I have a mixed reaction to showing this "C^1" expansion, and the "B^1 B^2 
> B^3" one as well.  I see the appeal of showing the parent notation, but 
> really that was already explained to death in the first section.

> Here it's distracting.  I think it's clearer for the reader to remove 
> these expansions and just use the node names from the illustration.
>
>> +          = F             I J F
>> +   B^@    = B^1 B^2 B^3
>> +          = D E F         D G H E F I J
>> +   C^!    = C ^C^1
>
> I think this expansion might be better expressed as "C ^C^@".

>        It'll be the same for "B^! = B ^B^@" as well, which demonstrates a 
> nice consistency and also helps to emphasize the meaning of the ^@ 
> notation.
>
>> +          = C ^F          C
>> +   B^! = B ^B^1 ^B^2 ^B^3
>> +       = B ^D ^E ^F       B
>
> The layout of these last two lines doesn't match the others.  They should 
> be:
>
>    B^!    = B ^B^1 ^B^2   ^B^3
>           = B ^D ^E ^F    B
>
> I see that the next patch fixes the layout of the unchanged examples, but 
> it leaves these two unaligned.

> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> ---
> new
> Junio's final comment https://public-inbox.org/git/xmqqwpkq6b4d.fsf%40gitster.mtv.corp.google.com/
> ---
>  Documentation/revisions.txt | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 0b5044d..934d071 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -284,6 +284,10 @@ The 'r1{caret}@' notation means all parents of 'r1'.
>  'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.
>  This is the single commit 'r1', if standalone.
>
> +While '<rev>{caret}<n>' was about specifying a single commit parent, these
> +two notations consider all its parents. For example you can say
> +'HEAD{caret}2^@', however you cannot say 'HEAD{caret}@{caret}2'.

> On 2016-08-12 03:07 AM, Philip Oakley wrote:
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>> new
>> Junio's final comment 
>> https://public-inbox.org/git/xmqqwpkq6b4d.fsf%40gitster.mtv.corp.google.com/
>> ---
>>  Documentation/revisions.txt | 4 ++++
>>  1 file changed, 4 insertions(+)
>>
>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
>> index 0b5044d..934d071 100644
>> --- a/Documentation/revisions.txt
>> +++ b/Documentation/revisions.txt
>> @@ -284,6 +284,10 @@ The 'r1{caret}@' notation means all parents of 'r1'.
>>  'r1{caret}!' notation includes commit 'r1' but excludes all of its 
>> parents.
>>  This is the single commit 'r1', if standalone.
>>
>> +While '<rev>{caret}<n>' was about specifying a single commit parent, 
>> these
>> +two notations consider all its parents. For example you can say
>> +'HEAD{caret}2^@', however you cannot say 'HEAD{caret}@{caret}2'.
>
> That ^ should be {caret}, right?
>

> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> ---
> new
> Cc: Jakub Narębski <jnareb@gmail.com>
> https://public-inbox.org/git/578E4F4A.2020708%40gmail.com/
> ---
>  Documentation/revisions.txt | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 3da0083..0b5044d 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -281,7 +281,8 @@ for naming a set that is formed by a commit and its parent commits.
>
>  The 'r1{caret}@' notation means all parents of 'r1'.
>
> -'r1{caret}!' includes commit 'r1' but excludes all of its parents.
> +'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.

> On 2016-08-12 03:07 AM, Philip Oakley wrote:
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>> new
>> Cc: Jakub Narębski <jnareb@gmail.com>
>> https://public-inbox.org/git/578E4F4A.2020708%40gmail.com/
>> ---
>>  Documentation/revisions.txt | 3 ++-
>>  1 file changed, 2 insertions(+), 1 deletion(-)
>>
>> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
>> index 3da0083..0b5044d 100644
>> --- a/Documentation/revisions.txt
>> +++ b/Documentation/revisions.txt
>> @@ -281,7 +281,8 @@ for naming a set that is formed by a commit and its 
>> parent commits.
>>
>>  The 'r1{caret}@' notation means all parents of 'r1'.
>>
>> -'r1{caret}!' includes commit 'r1' but excludes all of its parents.
>> +'r1{caret}!' notation includes commit 'r1' but excludes all of its 
>> parents.
>
> This sentence should start with "The".

>
>> +This is the single commit 'r1', if standalone.
>
> That reads awkwardly to me.  Perhaps
>
>        By itself, this notation denotes the single commit 'r1'.

>
> ?
>
> M.
>
> --

> On Tue, Jul 12, 2016 at 10:41:35PM +0100, Philip Oakley wrote:
> > Marc Branchaud <marcnarc@xiplink.com> 12 July 2016 14:44 noted
> > > +The '{caret}' (caret) notation
> > > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > >   To exclude commits reachable from a commit, a prefix '{caret}'
> > >   notation is used.  E.g. '{caret}r1 r2' means commits reachable
> > >   from 'r2' but exclude the ones reachable from 'r1'.
> >
> > All of these headings render poorly in the manpage, at least for me
> > (Ubuntu 16.04).  Only the first word appears in bold; the '-quoted text
> > is not bold but underlined, and the rest of the header is plain.
>
> Which doc package is that with? It had formatted OK for the html web pages.

> We do not quote the notation within the headings as the asciidoc ->
> docbook -> groff man viewer toolchain, particularly the docbook-groff
> step, does not cope with two font changes, failing to return the heading
> font to bold after the quotation of the notation.
> [...]
> The docbook folks have confirmed that \fP would only work across one
> level, so they cannot use it for their XSLT conversion which must be
> multi-level, so they always return to the default font.

> While there, also break out the other shorthand notations and
> add a title for the revision range summary (which also appears
> in git-rev-parse, so keep it mixed case).
>
> We do not quote the notation within the headings as the asciidoc ->
> docbook -> groff man viewer toolchain, particularly the docbook-groff
> step, does not cope with two font changes, failing to return the heading
> font to bold after the quotation of the notation.

> On 2016-08-12 03:07 AM, Philip Oakley wrote:
>> [2nd attempt : ISP troubles]
>>
>> This has grown like topsy from a little two patch series that tried to
>> name the 2-dots notation [1] into this extended set of tweaks.
>
> Honestly, I start just trying point out something concrete, like 
> misrendered headers, but then I figure since I'm sending a review comment 
> anyway I might as well go in-depth on the rest of the patch.
>
> I think I'm sticking to substantive comments, but if I'm getting too picky 
> please just swat me down!

>> Yup, I think "range" is the commonly used word in discussions here.
>> When inventing A...B as a new thing in addition to A..B, we called
>> the former "symmetric difference", and what is implied by that is
>> the latter is "asymmetric difference"; we do not say that unless we
>> are contrasting between the two, though.
>>
> I asked because the man page does indicae that it (A..B) is a special
> sort of revison range and "there is a shorthand for it", but then
> didn't have a way of naming it.

> The symmetric difference is then brought in as a further similar
> notation. There are a number of Stackoverflow questions about the
> differences betwee 'two dots' and 'three dots' as well, so having a
> word/phrase for it could help.
>
> I was thinking that maybe "single-sided difference (two dots)" maybe
> one choice that is relatively neutral (or even a "two-dot range"...).

> "Philip Oakley" <philipoakley@iee.org> writes:
>
>>> Yup, I think "range" is the commonly used word in discussions here.
>>> When inventing A...B as a new thing in addition to A..B, we called
>>> the former "symmetric difference", and what is implied by that is
>>> the latter is "asymmetric difference"; we do not say that unless we
>>> are contrasting between the two, though.
>>>
>> I asked because the man page does indicae that it (A..B) is a special
>> sort of revison range and "there is a shorthand for it", but then
>> didn't have a way of naming it.
>
> I do not see "is a special sort of revision range" improved in your
> two patches, though.

>
> Knowing that A..B is merely a short-hand for ^A B is important to
> understand how revision ranges work (e.g. "A..B C" is not "union of
> A..B and C"), so I think it is worth addressing if the existing
> description appeared to you that it may confuse readers.

>
>> The symmetric difference is then brought in as a further similar
>> notation. There are a number of Stackoverflow questions about the
>> differences betwee 'two dots' and 'three dots' as well, so having a
>> word/phrase for it could help.
>>
>> I was thinking that maybe "single-sided difference (two dots)" maybe
>> one choice that is relatively neutral (or even a "two-dot range"...).
>
> When contrasting .. and ..., we have always used "asymmetric" vs
> "symmetric".  I'd prefer to see usnot invent new phrase nobody has
> used, which leads to unnecessary confusion and learning burden.

> "Philip Oakley" <philipoakley@iee.org> writes:
> 
>> ..., I was wondering
>> if an alternative would be to refer to it via [use the headings of]
>> it's notation, i.e. "the 'two-dot' range notation" (or 'syntax' is
>> that is preferred), and the "three-dot symmetric difference notation".
> 
> That's a lot more sensible pair of headings, I would think.
> 
>> The existing explanatory text can stand as is, but they would now have
>> a section for readers to find.
>>
>> Or should I just drop this?
> 
> I like the approach to separate them into clearly marked sections.
> I primarily was reacting to the "single-sided" which nobody would
> understand.
> --