name for A..B ranges?

name for A..B ranges?

[Philip Oakley]

Hi,

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.

Philip 

Re: name for A..B ranges?

[Jeff King]

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.

-Peff

Re: name for A..B ranges?

[Junio C Hamano]

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.

Re: name for A..B ranges?

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> 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.
>
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 

[PATCH 0/2] Re: name for A..B ranges?

[Philip Oakley]

>> 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?
$gmane/297908

Here is a short two patch series to hopefully enhance the
revisions (and rev-parse) man page to help clarify the symmetric
difference and two / three dots notations.

The HTML versions look OK to me - tested on the Git-for-Windows SDK.

Philip Oakley (2):
  doc: use 'symmetric difference' consistently
  doc: give headings for the two and three dot notations

 Documentation/gitk.txt             |  2 +-
 Documentation/rev-list-options.txt |  4 ++--
 Documentation/revisions.txt        | 17 +++++++++++++----
 3 files changed, 16 insertions(+), 7 deletions(-)

-- 
2.8.4.windows.1.3.ge328a54

[PATCH 1/2] doc: use 'symmetric difference' consistently

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/gitk.txt             | 2 +-
 Documentation/rev-list-options.txt | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
index 6ade002..6c3eb15 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.txt
@@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.
 
 --left-right::
 
-	Mark which side of a symmetric diff a commit is reachable
+	Mark which side of a symmetric difference a commit is reachable
 	from.  Commits from the left side are prefixed with a `<`
 	symbol and those from the right with a `>` symbol.
 
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 `-`.
-- 
2.8.4.windows.1.3.ge328a54

[PATCH 2/2] doc: give headings for the two and three dot notations

[Philip Oakley]

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

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/revisions.txt | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 19314e3..c7e123a 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -246,12 +246,16 @@ 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'.
 
+Single-Sided Difference (two dots)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 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'.
 
+Symmetric Difference (three dots)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 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)'.
@@ -265,12 +269,17 @@ 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.
 
+The '{caret}' Shorthands
+~~~~~~~~~~~~~~~~~~~~~~~~
 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
+----------------------
 
 '<rev>'::
 	Include commits that are reachable from (i.e. ancestors of)
-- 
2.8.4.windows.1.3.ge328a54

[PATCH] doc: show the actual left, right, and boundary marks

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
This is a quick follow on to the 'symmetric difference' documentation patches
http://thread.gmane.org/gmane.comp.version-control.git/297908/focus=298223
where I checked all the uses of 'left' to see if other terms had been used.

I noticed that the actual marks were not being shown here, leaving the reader
with a difficult seach.


---
 Documentation/pretty-formats.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 29b19b9..10719e1 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -166,7 +166,7 @@ endif::git-rev-list[]
   respecting the `auto` settings of the former if we are going to a
   terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring
   on the next placeholders until the color is switched again.
-- '%m': left, right or boundary mark
+- '%m': left (`<`), right (`>`) or boundary (`-`) mark
 - '%n': newline
 - '%%': a raw '%'
 - '%x00': print a byte from a hex code
-- 
2.8.4.windows.1.3.ge328a54

[PATCH v2 0/4] Name for A..B ranges?

[Philip Oakley]

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.

Discussion: $gmane/297908
previous patch series $gmane/298223

Philip Oakley (4):
  doc: use 'symmetric difference' consistently
  doc: show the actual left, right, and boundary marks
  doc: give headings for the two and three dot notations
  doc: clarify that `^r1` will exclude `r1` itself

 Documentation/gitk.txt             |  2 +-
 Documentation/pretty-formats.txt   |  2 +-
 Documentation/rev-list-options.txt |  4 ++--
 Documentation/revisions.txt        | 25 ++++++++++++++++++-------
 4 files changed, 22 insertions(+), 11 deletions(-)

-- 
2.8.4.windows.1.3.ge328a54

[PATCH v2 1/4] doc: use 'symmetric difference' consistently

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/gitk.txt             | 2 +-
 Documentation/rev-list-options.txt | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
index 6ade002..6c3eb15 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.txt
@@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.
 
 --left-right::
 
-	Mark which side of a symmetric diff a commit is reachable
+	Mark which side of a symmetric difference a commit is reachable
 	from.  Commits from the left side are prefixed with a `<`
 	symbol and those from the right with a `>` symbol.
 
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 `-`.
-- 
2.8.4.windows.1.3.ge328a54

[PATCH v2 2/4] doc: show the actual left, right, and boundary marks

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
Found while checking the 'symmetric difference' documentation
---
 Documentation/pretty-formats.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 29b19b9..10719e1 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -166,7 +166,7 @@ endif::git-rev-list[]
   respecting the `auto` settings of the former if we are going to a
   terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring
   on the next placeholders until the color is switched again.
-- '%m': left, right or boundary mark
+- '%m': left (`<`), right (`>`) or boundary (`-`) mark
 - '%n': newline
 - '%%': a raw '%'
 - '%x00': print a byte from a hex code
-- 
2.8.4.windows.1.3.ge328a54

[PATCH v2 3/4] doc: give headings for the two and three dot notations

[Philip Oakley]

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 19314e3..131060c 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'.
 
-This set operation appears so often that there is a shorthand
+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' or 'r2' 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
+----------------------
 
 '<rev>'::
 	Include commits that are reachable from (i.e. ancestors of)
-- 
2.8.4.windows.1.3.ge328a54

[PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself

[Philip Oakley]

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'.
 
 The '..' (two-dot) range notation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.8.4.windows.1.3.ge328a54

Re: [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself

[Junio C Hamano]

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

Re: [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> 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,

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.

Describing 'reachability' is a whole different kettle of fish, as you
highlight below, and would be separate from this patch.

I've certainly tripped up in the past over using an appropriate reachability
definition in r1..r2, and forgetting (*) about remote branches being in the
local graph . (*- i.e. not really understanding!)

--
Philip
(only occasional access to internet over next few days)
>
> ... 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'.
>
> 

Re: [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself

[Junio C Hamano]

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?".

Re: [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself

[Junio C Hamano]

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?
>
>> 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?".

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.

But any other interpretation, e.g. 0,1,2,3,4, is incoherent.

Re: [PATCH v2 4/4] doc: clarify that `^r1` will exclude `r1` itself

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com> : Saturday, July 02, 2016 12:01 
AM
> 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'.
Hi Junio
Sorry for the delay in response, I'd been away and had some catch up to do.

I think we may have dropped into a YXproblem.

My particular concern was the literary conflict between the implicit 
'inclusive' aspects and the explicit 'exclusive' parts of the descriptions, 
a sort of barber shaving problem [1], especially when used in conjunction 
with the negation.

It's the potential for reader confusion at that point (particularly for a 
string of pearls case) I was trying to address. However, you are right that 
'reachable' also isn't as well defined as it might be.

For example, in a DAG, we should have no cycles where directed edges lead 
can back to their start point, yet (for reachability discussions) we want to 
imply an extra loopback edge, all of which is part of the sloppiness of 
natural languages.

This potential for confusion is further shown in the summary where both 
<rev> and ^<rev> say "(i.e. ancestors of)"!

In summary, I think that both the definition of reachability needs 
clarifying, and that c0ffee..deadbeef excludes any serving of c0ffee, even 
for a line of pearls, should be covered.

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

In most natural language we have 0:4 is 0,1,2,3,4 so the exclusion of 0 
would be the one to note.

>>
>>> Describing 'reachability' is a whole different kettle of fish, as you
>>> highlight below, and would be separate from this patch.
see below.

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

I don't think that just clarifying "reachability" would be sufficient. 
Necessary yes, sufficient no.

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

The understanding of this "Y" branching "range" is the part that was the 
'whole new kettle of fish' for me, especially with the rtbs, that caught me 
out during early contributions.


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

I'll re-think the patch (4/4) to cover thse issue.

>
> But any other interpretation, e.g. 0,1,2,3,4, is incoherent.
> --
Philip

[1] https://en.wikipedia.org/wiki/Barber_paradox 

Re: [PATCH v2 0/4] Name for A..B ranges?

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

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

Thanks.

I think 1-3 are ready for 'next'.  4/4 may need a bit more
thinking.

[PATCH v3 0/8] Name for A..B ranges?

[Philip Oakley]

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.

Original discussion starts at: $gmane/297908
V1 patch series $gmane/298223
V2 patch series $gmane/298689


Philip Oakley (8):
  doc: use 'symmetric difference' consistently
  doc: revisions - name the Left and Right sides
  doc: show the actual left, right, and boundary marks
  doc: give headings for the two and three dot notations
  doc: gitrevisions - use 'reachable' in page description
  doc: gitrevisions - clarify 'latter case' is revision walk
  doc: revisions  - define `reachable`
  doc: revisions - clarify reachability examples

 Documentation/gitk.txt             |  2 +-
 Documentation/gitrevisions.txt     |  6 ++---
 Documentation/pretty-formats.txt   |  2 +-
 Documentation/rev-list-options.txt |  4 +--
 Documentation/revisions.txt        | 50 ++++++++++++++++++++++++++------------
 5 files changed, 41 insertions(+), 23 deletions(-)

-- 
2.8.4.windows.1.3.ge328a54

follows from msg-ID <20160630202509.4472-1-philipoakley@iee.org>

[PATCH v3 1/8] doc: use 'symmetric difference' consistently

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/gitk.txt             | 2 +-
 Documentation/rev-list-options.txt | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
index 6ade002..6c3eb15 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.txt
@@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.
 
 --left-right::
 
-	Mark which side of a symmetric diff a commit is reachable
+	Mark which side of a symmetric difference a commit is reachable
 	from.  Commits from the left side are prefixed with a `<`
 	symbol and those from the right with a `>` symbol.
 
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 `-`.
-- 
2.8.4.windows.1.3.ge328a54

[PATCH v3 2/8] doc: revisions - name the Left and Right sides

[Philip Oakley]

The terms Left and Right side originate from the symmetric
difference. Name them there.
---
 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.
 
 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
-- 
2.8.4.windows.1.3.ge328a54

Re: [PATCH v3 2/8] doc: revisions - name the Left and Right sides

[Junio C Hamano]

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

Re: [PATCH v3 2/8] doc: revisions - name the Left and Right sides

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> Philip Oakley <philipoakley@iee.org> writes:
>
>> The terms Left and Right side originate from the symmetric
>> difference. Name them there.
>> ---
>
> Sign-off?

Oops - will fix.
>
>>  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.

OK - can fix.

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

[PATCH v3 3/8] doc: show the actual left, right, and boundary marks

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
Found while checking the 'symmetric difference' documentation
---
 Documentation/pretty-formats.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 29b19b9..10719e1 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -166,7 +166,7 @@ endif::git-rev-list[]
   respecting the `auto` settings of the former if we are going to a
   terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring
   on the next placeholders until the color is switched again.
-- '%m': left, right or boundary mark
+- '%m': left (`<`), right (`>`) or boundary (`-`) mark
 - '%n': newline
 - '%%': a raw '%'
 - '%x00': print a byte from a hex code
-- 
2.8.4.windows.1.3.ge328a54

[PATCH v3 4/8] doc: give headings for the two and three dot notations

[Philip Oakley]

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'.
 
-This set operation appears so often that there is a shorthand
+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 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
+----------------------
 
 '<rev>'::
 	Include commits that are reachable from (i.e. ancestors of)
-- 
2.8.4.windows.1.3.ge328a54

Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations

[Marc Branchaud]

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.


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

However, if you choose to keep this little section, you need to move the 
word "exist" earlier in the sentence:

	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.

		M.

Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations

[Junio C Hamano]

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

Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> 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.
>
OK - I'll see about incorporating that.

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

I'd just capitalised the specific term. Will change.

>>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>>>   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.

I'll look into that.

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

These two are special cases I'm not too familiar with, particularly the r1^! 
which I didn't undesrtand from the description...

--
Philip 

Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations

[Jakub Narębski]

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
-- 
Jakub Narębski

Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations

[Philip Oakley]

From: "Jakub Narębski" <jnareb@gmail.com>
>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
> -- 

The tricky part is seeing that, rather than being a depth wise range, it's 
actually a width wise range that is designed to cover the scenarios around 
merges

e.g. $ git rev-parse 6c71a849^!
or $ git rev-parse 6c71a849^@

In the doc that I'm updating I'll add a comment that it's particulalry 
useful around merges.

Mind you I did see dscho quote it in $gmane/299738
" You can also inspect the diff of a commit, using the ^! suffix, e.g.

  git difftool -x diff origin/master~3^!

--
Philip 

Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations

[Philip Oakley]

From: "Marc Branchaud" <marcnarc@xiplink.com>
> 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.

Which doc package is that with? It had formatted OK for the html web pages.

>
>
> Also, I think calling this "The ^ notation" is confusing, because there's 
> already an earlier paragraph on the "<rev>^" syntax.

Yes, I noticed that after sending. Maybe "^<rev>" (i.e. include the <rev> 
part) to show that its a prefix not a suffix

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

Part of the earlier discussions as about avoiding new termininologies just 
for the sake of it.

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


OK
>
>> +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.

OK

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

Isn't it that these are ranges of commits, rather than a single commit, so 
would go in this part of the docs, but I see your point.

>
> However, if you choose to keep this little section, you need to move the 
> word "exist" earlier in the sentence:

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

In the contect of the other pages it's included in, the use of lower case, 
is the next down level. ALL CAPS would be the top level heading.

I'll review.
--
Philip 

Re: [PATCH v3 4/8] doc: give headings for the two and three dot notations

[Jeff King]

On Tue, Jul 12, 2016 at 10:41:35PM +0100, Philip Oakley wrote:

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

I get the same with:

  make gitrevisions.7
  man -l gitrevisions.7

Asciidoc 8.6.9, docbook-xsl 4.5 if it matters.

Rendering single-quotes as underline is normal in this case (though it's
not great for punctuation like this, as it kind of blends with the dots;
I know we use it elsewhere in this document, though).  The failure to
continue the bold through the end of line looks like a bug, though.

The generated XML (from asciidoc) looks reasonable:

  <title>The <emphasis>..</emphasis> (two-dot) range notation</title>

The roff looks like:

  .SS "The \fI\&.\&.\fR (two\-dot) range notation"

The "\fR" switches us back to "Roman" from italics, which is presumably
the problem. We really want to say "switch back what we were using
before \fI".

Switching it to "\fP" fixes it, but it's not clear to me if that's
actually portable, or a groff-ism. I don't know roff very well and
documentation seems to be quite hard to find. So it's either a bug in
docbook, or an intentional decision they've made because roff can't
portably do better. I'm not sure which.

-Peff

[PATCH v3 5/8] doc: gitrevisions - use 'reachable' in page description

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/gitrevisions.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt
index e903eb7..33039c6 100644
--- a/Documentation/gitrevisions.txt
+++ b/Documentation/gitrevisions.txt
@@ -15,8 +15,8 @@ DESCRIPTION
 
 Many Git commands take revision parameters as arguments. Depending on
 the command, they denote a specific commit or, for commands which
-walk the revision graph (such as linkgit:git-log[1]), all commits which can
-be reached from that commit. In the latter case one can also specify a
+walk the revision graph (such as linkgit:git-log[1]), all commits which are
+reachable from that commit. In the latter case one can also specify a
 range of revisions explicitly.
 
 In addition, some Git commands (such as linkgit:git-show[1]) also take
-- 
2.8.4.windows.1.3.ge328a54

[PATCH v3 6/8] doc: gitrevisions - clarify 'latter case' is revision walk

[Philip Oakley]

The prior sentence has too many clauses for easy parsing.
Replace 'the latter case' with a direct quote.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/gitrevisions.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt
index 33039c6..27dec5b 100644
--- a/Documentation/gitrevisions.txt
+++ b/Documentation/gitrevisions.txt
@@ -16,8 +16,8 @@ DESCRIPTION
 Many Git commands take revision parameters as arguments. Depending on
 the command, they denote a specific commit or, for commands which
 walk the revision graph (such as linkgit:git-log[1]), all commits which are
-reachable from that commit. In the latter case one can also specify a
-range of revisions explicitly.
+reachable from that commit. For commands that walk the revision graph one can
+also specify a range of revisions explicitly.
 
 In addition, some Git commands (such as linkgit:git-show[1]) also take
 revision parameters which denote other objects than commits, e.g. blobs
-- 
2.8.4.windows.1.3.ge328a54

[PATCH v3 7/8] doc: revisions - define `reachable`

[Philip Oakley]

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.
+
+A commit's reachable set is the commit itself and the commits of
+its ancestry chain.
+
 
 The '{caret}' (caret) notation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.8.4.windows.1.3.ge328a54

Re: [PATCH v3 7/8] doc: revisions - define `reachable`

[Marc Branchaud]

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/

		M.

Re: [PATCH v3 7/8] doc: revisions - define `reachable`

[Philip Oakley]

From: "Marc Branchaud" <marcnarc@xiplink.com>
> 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."

OK. The main aspect is show that 'reachable' is a specific term.

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

OK.
>
--
Philip 

[PATCH v3 8/8] doc: revisions - clarify reachability examples

[Philip Oakley]

For the r1..r2 case, the exclusion of r1, rather than inclusion of r2,
would be the unexpected case in natural language for a simple linear
development, i.e. start..end excludes start.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/revisions.txt | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index a3cd28b..dba4fc6 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -252,7 +252,8 @@ 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 those reachable from 'r1' (i.e. 'r1' and its
+ancestors).
 
 The '..' (two-dot) range notation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -290,12 +291,12 @@ Revision Range Summary
 ----------------------
 
 '<rev>'::
-	Include commits that are reachable from (i.e. ancestors of)
-	<rev>.
+	Include commits that are reachable from <rev> (i.e. <rev> and its
+	ancestors).
 
 '{caret}<rev>'::
-	Exclude commits that are reachable from (i.e. ancestors of)
-	<rev>.
+	Exclude commits that are reachable from <rev> (i.e. <rev> and its
+	ancestors).
 
 '<rev1>..<rev2>'::
 	Include commits that are reachable from <rev2> but exclude
-- 
2.8.4.windows.1.3.ge328a54

Re: [PATCH v3 0/8] Name for A..B ranges?

[Junio C Hamano]

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

Looked mostly sensible, except for a few things mentioned in the
reviews by Marc (to which I mostly agree with).

Thanks.

Re: [PATCH v3 0/8] Name for A..B ranges?

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> 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).
> 

Thanks. I'll update in the next few days.

Philip

[PATCH v4 0/8] Name for A..B ranges?

[Philip Oakley]

This is the V4 re-roll of the po/range-doc (2016-07-01) 3 commits and its
follow on patch.

Capitalisation has been fixed.
Heading levels for man pages has been fixed.
Quoting of the caret has been fixed.
The extra width wise 'caret' shorthands now mention their applicability to merge commits.

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.

The patches can be squashed together if required.

Original discussion starts at: $gmane/297908
V1 patch series $gmane/298223
V2 patch series $gmane/298689
V3 patch series $gmane/299293


Philip Oakley (8):
  doc: use 'symmetric difference' consistently
  doc: revisions - name the left and right sides
  doc: show the actual left, right, and boundary marks
  doc: give headings for the two and three dot notations
  doc: gitrevisions - use 'reachable' in page description
  doc: gitrevisions - clarify 'latter case' is revision walk
  doc: revisions  - define `reachable`
  doc: revisions - clarify reachability examples

 Documentation/gitk.txt             |  2 +-
 Documentation/gitrevisions.txt     |  6 +--
 Documentation/pretty-formats.txt   |  2 +-
 Documentation/rev-list-options.txt |  4 +-
 Documentation/revisions.txt        | 83 ++++++++++++++++++++++++--------------
 5 files changed, 59 insertions(+), 38 deletions(-)

 interdiff:
 
 diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index dba4fc6..14622cc 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -241,35 +241,38 @@ 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
+previous section, means the set of commits `reachable` from the given
 commit.
 
-A commit's reachable set is the commit itself and the commits of
+A commit's reachable set is the commit itself and the commits in
 its 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 those reachable from 'r1' (i.e. 'r1' and its
-ancestors).
-
-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.
+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' (i.e. 'r1' and
+ its ancestors).
+
+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
@@ -278,10 +281,10 @@ 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.
+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.
 
 The 'r1{caret}@' notation means all parents of 'r1'.
 

-- 
2.9.0.windows.1

[PATCH v4 1/8] doc: use 'symmetric difference' consistently

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/gitk.txt             | 2 +-
 Documentation/rev-list-options.txt | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
index 6ade002..6c3eb15 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.txt
@@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.
 
 --left-right::
 
-	Mark which side of a symmetric diff a commit is reachable
+	Mark which side of a symmetric difference a commit is reachable
 	from.  Commits from the left side are prefixed with a `<`
 	symbol and those from the right with a `>` symbol.
 
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 `-`.
-- 
2.9.0.windows.1

[PATCH v4 2/8] doc: revisions - name the left and right sides

[Philip Oakley]

The terms left and right side originate from the symmetric
difference. Name them there.

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 19314e3..6e9cd41 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.
 
 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
-- 
2.9.0.windows.1

[PATCH v4 3/8] doc: show the actual left, right, and boundary marks

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
Found while checking the 'symmetric difference' documentation
---
 Documentation/pretty-formats.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 29b19b9..10719e1 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -166,7 +166,7 @@ endif::git-rev-list[]
   respecting the `auto` settings of the former if we are going to a
   terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring
   on the next placeholders until the color is switched again.
-- '%m': left, right or boundary mark
+- '%m': left (`<`), right (`>`) or boundary (`-`) mark
 - '%n': newline
 - '%%': a raw '%'
 - '%x00': print a byte from a hex code
-- 
2.9.0.windows.1

[PATCH v4 4/8] doc: give headings for the two and three dot notations

[Philip Oakley]

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.
+
+Revision Range Summary
+----------------------
 
 '<rev>'::
 	Include commits that are reachable from (i.e. ancestors of)
-- 
2.9.0.windows.1

Re: [PATCH v4 4/8] doc: give headings for the two and three dot notations

[Marc Branchaud]

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.

But, really, this means that the notation is another "Commit Exclusion" 
and properly belongs in that section.

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.

		M.

Re: [PATCH v4 4/8] doc: give headings for the two and three dot notations

[Philip Oakley]

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.

Identifying an example could be good if it was succinct and explanatory.

$ 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).

At the moment I'm minded to keep it as is unless others chime in.

>
> M.
>
I'll be away till mid next week.
--
Philip 

Re: [PATCH v4 4/8] doc: give headings for the two and three dot notations

[Marc Branchaud]

On 2016-07-21 03:54 PM, Philip Oakley wrote:
> 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)

Only the word "Special" is emphasized (in bold).  The rest of the header 
is plain.

I'm using asciidoc 8.6.9, so I'm likely suffering from the bug Peff 
identified.

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

Obviously, I see it more an anti-range.  You're never going to get more 
than a single commit with this notation.

> Identifying an example could be good if it was succinct and explanatory.

What do you think of my example?

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

"Specifying Commit Parents"?  Any of these work for me, really.

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

IMHO it has to look like it's part of the SPECIFYING RANGES section.  It 
need not be higher than the other subsections though.

> At the moment I'm minded to keep it as is unless others chime in.

I'll bow to the will of the majority.

>>
>> M.
>>
> I'll be away till mid next week.

As will I!

		M.

Re: [PATCH v4 4/8] doc: give headings for the two and three dot notations

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

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

As these are not all that "special", how about retitling this
section as:

	Other Shorthand Notations
        ~~~~~~~~~~~~~~~~~~~~~~~~~


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

[PATCH v4 5/8] doc: gitrevisions - use 'reachable' in page description

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/gitrevisions.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt
index e903eb7..33039c6 100644
--- a/Documentation/gitrevisions.txt
+++ b/Documentation/gitrevisions.txt
@@ -15,8 +15,8 @@ DESCRIPTION
 
 Many Git commands take revision parameters as arguments. Depending on
 the command, they denote a specific commit or, for commands which
-walk the revision graph (such as linkgit:git-log[1]), all commits which can
-be reached from that commit. In the latter case one can also specify a
+walk the revision graph (such as linkgit:git-log[1]), all commits which are
+reachable from that commit. In the latter case one can also specify a
 range of revisions explicitly.
 
 In addition, some Git commands (such as linkgit:git-show[1]) also take
-- 
2.9.0.windows.1

[PATCH v4 6/8] doc: gitrevisions - clarify 'latter case' is revision walk

[Philip Oakley]

The prior sentence has too many clauses for easy parsing.
Replace 'the latter case' with a direct quote.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/gitrevisions.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt
index 33039c6..27dec5b 100644
--- a/Documentation/gitrevisions.txt
+++ b/Documentation/gitrevisions.txt
@@ -16,8 +16,8 @@ DESCRIPTION
 Many Git commands take revision parameters as arguments. Depending on
 the command, they denote a specific commit or, for commands which
 walk the revision graph (such as linkgit:git-log[1]), all commits which are
-reachable from that commit. In the latter case one can also specify a
-range of revisions explicitly.
+reachable from that commit. For commands that walk the revision graph one can
+also specify a range of revisions explicitly.
 
 In addition, some Git commands (such as linkgit:git-show[1]) also take
 revision parameters which denote other objects than commits, e.g. blobs
-- 
2.9.0.windows.1

[PATCH v4 7/8] doc: revisions - define `reachable`

[Philip Oakley]

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 5b37283..d3b7cee 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 set of commits `reachable` from the given
+commit.
+
+A commit's reachable set is the commit itself and the commits in
+its ancestry chain.
+
 
 Commit Exclusions
 ~~~~~~~~~~~~~~~~~
-- 
2.9.0.windows.1

[PATCH v4 8/8] doc: revisions - clarify reachability examples

[Philip Oakley]

 For the r1..r2 case, the exclusion of r1, rather than inclusion of r2,
 would be the unexpected case in natural language for a simple linear
 development, i.e. start..end excludes start.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/revisions.txt | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index d3b7cee..14622cc 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -254,7 +254,8 @@ 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'.
+ from 'r2' but exclude the ones reachable from 'r1' (i.e. 'r1' and
+ its ancestors).
 
 Dotted Range Notations
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -293,12 +294,12 @@ Revision Range Summary
 ----------------------
 
 '<rev>'::
-	Include commits that are reachable from (i.e. ancestors of)
-	<rev>.
+	Include commits that are reachable from <rev> (i.e. <rev> and its
+	ancestors).
 
 '{caret}<rev>'::
-	Exclude commits that are reachable from (i.e. ancestors of)
-	<rev>.
+	Exclude commits that are reachable from <rev> (i.e. <rev> and its
+	ancestors).
 
 '<rev1>..<rev2>'::
 	Include commits that are reachable from <rev2> but exclude
-- 
2.9.0.windows.1

Re: [PATCH v4 0/8] Name for A..B ranges?

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

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

All looked sensible and each focused on a single issue and fixing it
well.  Done very nicely.

Thanks.  Will (re)queue, wait for a few days for further comments
and let's merge it to 'next'.

[PATCH v5 00/12] Update git revisions

[Philip Oakley]

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

[PATCH v5 01/12] doc: use 'symmetric difference' consistently

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
unchanged
---
 Documentation/gitk.txt             | 2 +-
 Documentation/rev-list-options.txt | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
index 6ade002..6c3eb15 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.txt
@@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.
 
 --left-right::
 
-	Mark which side of a symmetric diff a commit is reachable
+	Mark which side of a symmetric difference a commit is reachable
 	from.  Commits from the left side are prefixed with a `<`
 	symbol and those from the right with a `>` symbol.
 
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 `-`.
-- 
2.9.0.windows.1

Re: [PATCH v5 01/12] doc: use 'symmetric difference' consistently

[Jakub Narębski]

W dniu 11.08.2016 o 23:50, Philip Oakley pisze:
  
> 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 `-`.

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

Best,
-- 
Jakub Narębski

Re: [PATCH v5 01/12] doc: use 'symmetric difference' consistently

[Junio C Hamano]

Jakub Narębski <jnareb@gmail.com> writes:

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

By "symmetric difference", we mean a "set difference" operation that
is symmetric.  Contrasting with asymmetric difference that gives a
set of elements that belong to set A but do not belong to set B
(i.e. B..A), symmetric difference of set A and set B gives a set of
elements that belong to either set A alone or set B alone but not
both (i.e. A...B).

So if you really want a fully spelled name, we would not want to
call it with a name with "range".  It is "symmetric set difference",
and "symmetric difference" in the updated sentence is a short-hand
for that.

Re: [PATCH v5 00/12] Update git revisions

[Philip Oakley]

I'm having trouble with my ISP is not playing ball. only cover and patch 1 
were sent.

Will retry with alternate service.

Philip
----- Original Message ----- 
From: "Philip Oakley" <philipoakley@iee.org>
Sent: Thursday, August 11, 2016 10:50 PM
Subject: [PATCH v5 00/12] Update git revisions


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

[PATCH v6 00/12] Update git revisions

[Philip Oakley]

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.

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

-- 
2.9.0.windows.1

[PATCH v6 05/12] doc: revisions: extra clarification of <rev>^! notation effects

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
v6 updated
Cc: Jakub Narębski <jnareb@gmail.com>
Cc: Marc Branchaud <marcnarc@xiplink.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..17fc45c 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.
+The 'r1{caret}!' notation includes commit 'r1' but excludes all of its parents.
+By itself, this notation denotes the single commit 'r1'.
 
 Revision Range Summary
 ----------------------
-- 
2.9.0.windows.1

[PATCH v6 06/12] doc: revisions: single vs multi-parent notation comparison

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
v6 updated
Junio's final comment https://public-inbox.org/git/xmqqwpkq6b4d.fsf%40gitster.mtv.corp.google.com/
Cc: Marc Branchaud <marcnarc@xiplink.com>
---
 Documentation/revisions.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 17fc45c..242123b 100644
--- 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'.
+
 Revision Range Summary
 ----------------------
 
-- 
2.9.0.windows.1

Re: [PATCH v6 06/12] doc: revisions: single vs multi-parent notation comparison

[Jakub Narębski]

W dniu 13.08.2016 o 01:45, Philip Oakley pisze:

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

That's good to have.

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.

Anyway, good addition!
-- 
Jakub Narębski

Re: [PATCH v6 06/12] doc: revisions: single vs multi-parent notation comparison

[Junio C Hamano]

Jakub Narębski <jnareb@gmail.com> writes:

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

I think that the answer you are giving to the question is the latter,
and I tend to agree with you.

You could define: A^@ followed by <anything> means first expand A^@,
and then apply that <anything> to each and every one in the resulting
set.  But some may be merges and while others not.  It is unclear
what should happen to A^@^2 when one of A's parents has only one
parent.  In some use cases, it would be convenient if parents of A
to which the <anything> operation cannot be applied, but in other
use cases, it would be convenient if the whole thing caused an error.
The notation is not detailed/rich enough to express the distinction.

[PATCH v6 11/12] doc: revisions: show revision expansion in examples

[Philip Oakley]

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>
---
v6 updated
Cc: Jakub Narębski <jnareb@gmail.com>
Cc: Marc Branchaud <marcnarc@xiplink.com>
---
 Documentation/revisions.txt | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index e9a74fc..f15d5ed 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -326,16 +326,27 @@ 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,
+with each step in the notation's expansion and selection carefully
+spelt out:
 
+   Args   Expanded arguments    Selected commits
    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
+          = F                   I J F
+   B^@    = B^1 B^2 B^3
+          = D E F               D G H E F I J
+   C^!    = C ^C^@
+          = C ^C^1
+          = C ^F                C
+   B^!    = B ^B^@
+          = B ^B^1 ^B^2 ^B^3
+          = B ^D ^E ^F          B
+   F^! D  = F ^I ^J D           G H D F
-- 
2.9.0.windows.1

[PATCH v6 12/12] doc: revisions: sort examples and fix alignment of the unchanged

[Philip Oakley]

The previous commit adjusted the column alignment for revision
examples which show expansion. Fix the unchanged examples and sort
those that show expansions to the end of the list.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
v6 updated
Cc: Marc Branchaud <marcnarc@xiplink.com>
---
 Documentation/revisions.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index f15d5ed..b9b45c0 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -331,14 +331,14 @@ with each step in the notation's expansion and selection carefully
 spelt out:
 
    Args   Expanded arguments    Selected commits
-   D                G H D
-   D F              G H I J D F
-   ^G D             H D
-   ^D B             E I J F B
+   D                            G H D
+   D F                          G H I J D F
+   ^G D                         H D
+   ^D B                         E I J F B
+   ^D B C                       E I J F B C
+   C                            I J F 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^@    = C^1
           = F                   I J F
    B^@    = B^1 B^2 B^3
-- 
2.9.0.windows.1

Re: [PATCH v6 00/12] Update git revisions

[Marc Branchaud]

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

Re: [PATCH v6 00/12] Update git revisions

[Philip Oakley]

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


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

BUG: indent-with-non-tab always on (was: Re: [PATCH v6 00/12] Update git revisions)

[Marc Branchaud]

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.

		M.

Re: BUG: indent-with-non-tab always on

[Marc Branchaud]

On 2016-08-15 12:55 PM, Marc Branchaud wrote:
> 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.

Gah, never mind -- didn't realize it was turned on in 
Documentation/.gitattributes.

		M.

Re: [PATCH v6 00/12] Update git revisions

[Junio C Hamano]

Marc Branchaud <marcnarc@xiplink.com> writes:

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

Probably that is because Documentation/.gitattributes has

	*.txt whitespace

to tell Git to notice all types of potential whitespace errors known
to it.  The checking of indent-with-tab is deliberate here, because
we rely on the fact that asciidoc treats HT as "fill with necessary
spaces to next multiple of 8" even when it renders a fixed-column
drawing.

Re: [PATCH v6 00/12] Update git revisions

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

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

I gave a cursory re-read on the whole thing again, and spotted no
further issue.  This has been kept in the "Undecided" pile, but I'll
mark it as "Will merge to 'next'" and hope to have it in 'master'
early in the post 2.10 cycle.

Thanks.

[PATCH v5 00/12] Update git revisions

[Philip Oakley]

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

[PATCH v5 01/12] doc: use 'symmetric difference' consistently

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
unchanged
---
 Documentation/gitk.txt             | 2 +-
 Documentation/rev-list-options.txt | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
index 6ade002..6c3eb15 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.txt
@@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.
 
 --left-right::
 
-	Mark which side of a symmetric diff a commit is reachable
+	Mark which side of a symmetric difference a commit is reachable
 	from.  Commits from the left side are prefixed with a `<`
 	symbol and those from the right with a `>` symbol.
 
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 `-`.
-- 
2.9.0.windows.1

[PATCH v5 00/12] Update git revisions

[Philip Oakley]

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

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

[PATCH v5 01/12] doc: use 'symmetric difference' consistently

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
unchanged
---
 Documentation/gitk.txt             | 2 +-
 Documentation/rev-list-options.txt | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt
index 6ade002..6c3eb15 100644
--- a/Documentation/gitk.txt
+++ b/Documentation/gitk.txt
@@ -70,7 +70,7 @@ linkgit:git-rev-list[1] for a complete list.
 
 --left-right::
 
-	Mark which side of a symmetric diff a commit is reachable
+	Mark which side of a symmetric difference a commit is reachable
 	from.  Commits from the left side are prefixed with a `<`
 	symbol and those from the right with a `>` symbol.
 
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 `-`.
-- 
2.9.0.windows.1

[PATCH v5 02/12] doc: revisions - name the left and right sides

[Philip Oakley]

The terms left and right side originate from the symmetric
difference. Name them there.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
unchanged
---
 Documentation/revisions.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 19314e3..6e9cd41 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.
 
 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
-- 
2.9.0.windows.1

[PATCH v5 03/12] doc: show the actual left, right, and boundary marks

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
Found while checking the 'symmetric difference' documentation
Unchanged from v4
---
 Documentation/pretty-formats.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index 29b19b9..10719e1 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -166,7 +166,7 @@ endif::git-rev-list[]
   respecting the `auto` settings of the former if we are going to a
   terminal). `auto` alone (i.e. `%C(auto)`) will turn on auto coloring
   on the next placeholders until the color is switched again.
-- '%m': left, right or boundary mark
+- '%m': left (`<`), right (`>`) or boundary (`-`) mark
 - '%n': newline
 - '%%': a raw '%'
 - '%x00': print a byte from a hex code
-- 
2.9.0.windows.1

[PATCH v5 04/12] doc: revisions: give headings for the two and three dot notations

[Philip Oakley]

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.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
Cc: Marc Branchaud <marcnarc@xiplink.com>
Cc: Jeff King <peff@peff.net>

ref email

Jeff King wrote on 12 July 2016 23:12
> 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.

I get the same with:

  make gitrevisions.7
  man -l gitrevisions.7

Asciidoc 8.6.9, docbook-xsl 4.5 if it matters.

Rendering single-quotes as underline is normal in this case (though it's
not great for punctuation like this, as it kind of blends with the dots;
I know we use it elsewhere in this document, though).  The failure to
continue the bold through the end of line looks like a bug, though.

The generated XML (from asciidoc) looks reasonable:

  <title>The <emphasis>..</emphasis> (two-dot) range notation</title>

The roff looks like:

  .SS "The \fI\&.\&.\fR (two\-dot) range notation"

The "\fR" switches us back to "Roman" from italics, which is presumably
the problem. We really want to say "switch back what we were using
before \fI".

Switching it to "\fP" fixes it, but it's not clear to me if that's
actually portable, or a groff-ism. I don't know roff very well and
documentation seems to be quite hard to find. So it's either a bug in
docbook, or an intentional decision they've made because roff can't
portably do better. I'm not sure which.

-Peff

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.
-Philip
---
 Documentation/revisions.txt | 58 ++++++++++++++++++++++++++++-----------------
 1 file changed, 36 insertions(+), 22 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 6e9cd41..3da0083 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.
+Other <rev>{caret} Parent Shorthand Notations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Two other shorthands exist, particularly useful for merge commits,
+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
+----------------------
 
 '<rev>'::
 	Include commits that are reachable from (i.e. ancestors of)
-- 
2.9.0.windows.1

Re: [PATCH v5 04/12] doc: revisions: give headings for the two and three dot notations

[Jeff King]

On Fri, Aug 12, 2016 at 08:07:41AM +0100, Philip Oakley wrote:

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

Thanks for digging into the root cause. I think your workaround (to
avoid quoted bits in headers) is reasonable, and a rule we can keep in
mind for future patches.

-Peff

Re: [PATCH v5 04/12] doc: revisions: give headings for the two and three dot notations

[Marc Branchaud]

On 2016-08-12 03:07 AM, 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).
>
> 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.

Looks good --thanks!

		M.

[PATCH v5 05/12] doc: revisions: extra clarification of <rev>^! notation effects

[Philip Oakley]

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 is the single commit 'r1', if standalone.
 
 Revision Range Summary
 ----------------------
-- 
2.9.0.windows.1

Re: [PATCH v5 05/12] doc: revisions: extra clarification of <rev>^! notation effects

[Marc Branchaud]

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.

Re: [PATCH v5 05/12] doc: revisions: extra clarification of <rev>^! notation effects

[Philip Oakley]

From: "Marc Branchaud" <marcnarc@xiplink.com>
> 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".

Accepted. I'd simply split the the previous text, so the nice run-on effect 
it initially had has been lost.

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

Like it. I'd toyed wth quite a few variants. It's jsut a case of finding the 
nicest one;-)

>
> ?
>
> M.
>
> --

Philip 

[PATCH v5 06/12] doc: revisions: single vs multi-parent notation comparison

[Philip Oakley]

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'.
+
 Revision Range Summary
 ----------------------
 
-- 
2.9.0.windows.1

Re: [PATCH v5 06/12] doc: revisions: single vs multi-parent notation comparison

[Marc Branchaud]

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?

		M.

Re: [PATCH v5 06/12] doc: revisions: single vs multi-parent notation comparison

[Philip Oakley]

From: "Marc Branchaud" <marcnarc@xiplink.com>
> 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?
>
Yes (I think so - will change).

I had planned to change it but it looks like I missed it.

In an earlier version I hadn't changed any of them (or maybe just one) and 
the asciidoc barfed. I suspect that the ^ ^ symbols have to be paired 
properly, and a bad pairing around / across the quotes makes the parsing 
fail. it looks like singletons (which clearly never pair) are accespted 'as 
is'

I think the later examples are inside some form of a block quote with no 
expansions at all.

--
Philip


> M.
>
> 

[PATCH v5 07/12] doc: gitrevisions - use 'reachable' in page description

[Philip Oakley]

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
unchanged
---
 Documentation/gitrevisions.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt
index e903eb7..33039c6 100644
--- a/Documentation/gitrevisions.txt
+++ b/Documentation/gitrevisions.txt
@@ -15,8 +15,8 @@ DESCRIPTION
 
 Many Git commands take revision parameters as arguments. Depending on
 the command, they denote a specific commit or, for commands which
-walk the revision graph (such as linkgit:git-log[1]), all commits which can
-be reached from that commit. In the latter case one can also specify a
+walk the revision graph (such as linkgit:git-log[1]), all commits which are
+reachable from that commit. In the latter case one can also specify a
 range of revisions explicitly.
 
 In addition, some Git commands (such as linkgit:git-show[1]) also take
-- 
2.9.0.windows.1

[PATCH v5 08/12] doc: gitrevisions - clarify 'latter case' is revision walk

[Philip Oakley]

The prior sentence has too many clauses for easy parsing.
Replace 'the latter case' with a direct quote.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
unchanged
---
 Documentation/gitrevisions.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/gitrevisions.txt b/Documentation/gitrevisions.txt
index 33039c6..27dec5b 100644
--- a/Documentation/gitrevisions.txt
+++ b/Documentation/gitrevisions.txt
@@ -16,8 +16,8 @@ DESCRIPTION
 Many Git commands take revision parameters as arguments. Depending on
 the command, they denote a specific commit or, for commands which
 walk the revision graph (such as linkgit:git-log[1]), all commits which are
-reachable from that commit. In the latter case one can also specify a
-range of revisions explicitly.
+reachable from that commit. For commands that walk the revision graph one can
+also specify a range of revisions explicitly.
 
 In addition, some Git commands (such as linkgit:git-show[1]) also take
 revision parameters which denote other objects than commits, e.g. blobs
-- 
2.9.0.windows.1

[PATCH v5 09/12] doc: revisions - define `reachable`

[Philip Oakley]

Do not self-define `reachable`, which can lead to misunderstanding.
Instead define `reachability` explictly.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
unchanged
---
 Documentation/revisions.txt | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 934d071..238be45 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 set of commits `reachable` from the given
+commit.
+
+A commit's reachable set is the commit itself and the commits in
+its ancestry chain.
+
 
 Commit Exclusions
 ~~~~~~~~~~~~~~~~~
-- 
2.9.0.windows.1

Re: [PATCH v5 09/12] doc: revisions - define `reachable`

[Jakub Narębski]

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

Re: [PATCH v5 09/12] doc: revisions - define `reachable`

[Philip Oakley]

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:
> [...]
>
>>  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?

Strange as in 'not reflowed'? - yes that was the reason. It can be hard to 
see the wood from the trees if there is a lot of reflow going on, as it can 
hide the issue behind the key change.

I did slightly abuse notation by quoting `reachable` to indicate that it's a 
term with a precise definition that can be confusing to those that don't 
know. I also split out the reachability parts into their own paragraphs.

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

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?
>
> -- 
> Jakub Narębski
>
> 

Re: [PATCH v5 09/12] doc: revisions - define `reachable`

[Jakub Narębski]

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

Re: [PATCH v5 09/12] doc: revisions - define `reachable`

[Philip Oakley]

From: "Jakub Narębski" <jnareb@gmail.com>
>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
--
Thanks.

Philip 

[PATCH v5 10/12] doc: revisions - clarify reachability examples

[Philip Oakley]

 For the r1..r2 case, the exclusion of r1, rather than inclusion of r2,
 would be the unexpected case in natural language for a simple linear
 development, i.e. start..end excludes start.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
unchanged
---
 Documentation/revisions.txt | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 238be45..70864d5 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -254,7 +254,8 @@ 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'.
+ from 'r2' but exclude the ones reachable from 'r1' (i.e. 'r1' and
+ its ancestors).
 
 Dotted Range Notations
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -298,12 +299,12 @@ Revision Range Summary
 ----------------------
 
 '<rev>'::
-	Include commits that are reachable from (i.e. ancestors of)
-	<rev>.
+	Include commits that are reachable from <rev> (i.e. <rev> and its
+	ancestors).
 
 '{caret}<rev>'::
-	Exclude commits that are reachable from (i.e. ancestors of)
-	<rev>.
+	Exclude commits that are reachable from <rev> (i.e. <rev> and its
+	ancestors).
 
 '<rev1>..<rev2>'::
 	Include commits that are reachable from <rev2> but exclude
-- 
2.9.0.windows.1

[PATCH v5 11/12] doc: revisions: show revision expansion in examples

[Philip Oakley]

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
+          = 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
+          = C ^F          C
+   B^! = B ^B^1 ^B^2 ^B^3
+       = B ^D ^E ^F       B
+   F^! D  = F ^I ^J D     G H D F
-- 
2.9.0.windows.1

Re: [PATCH v5 11/12] doc: revisions: show revision expansion in examples

[Marc Branchaud]

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.

Also, shouldn't all the ^ in these examples be {caret}?  (I likely just 
don't understand the rationale for using {caret} in some places and ^ in 
others...)

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

		M.

Re: [PATCH v5 11/12] doc: revisions: show revision expansion in examples

[Philip Oakley]

From: "Marc Branchaud" <marcnarc@xiplink.com>
> 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.

I wanted to avoid that. I feel that "Result" is too general. I had thought 
about using the 'ed' rather than 'ion' word endings, but that would require 
(to my mind) the noun e.g. "Expanded arguments" and " Selected commits" 
(still could be - see below), while the 'ion' endings felt complete. The 
Result is what is shown in thable below these headings ;-)


>
> Also, shouldn't all the ^ in these examples be {caret}?  (I likely just 
> don't understand the rationale for using {caret} in some places and ^ in 
> others...)

All the conversions appear to work. I think that asciidoc is viewing these a 
blocked text without any expansion. Plus, it would be horrendous trying to 
check the formatting (endless reruns of make.. ... .. )

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

This was the whole point. For some (e.g. me) the explanations had fallen 
flat on their face, and it was difficult to see what it was on about. Now I 
know, it's all obvious, but what was needed was a carefully stepped through 
example or two. If the dear reader can't see the big steps, let's give them 
small steps.

Jacob had given an 'example' in response to my early query, but it just felt 
like repetion of what had already been said, but it didn't take the next 
[small] step, which this example does (partly because it can as it can use 
the Loeliger diagram, which wasn't available in Jacob's example).

I also deliberately added the B^@ and B^! (standalone) example as the C^@ 
and C^!  didn't have an 'all parents' (plurals!), but it did have the 
indentation issue - see above about stretching out the headers, which would 
give more space for the indentations.

> 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^@".

I hadn't viewed it that way. It would be an extra step.

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

As noted it was about squeezing that one in. I'll look at alternate heading 
titles and spacing options.


--
Philip 

[PATCH v5 12/12] doc: revisions: sort examples and fix alignment of the unchanged

[Philip Oakley]

The previous commit adjusted the column alignment for revision
examples which show expansion. Fix the unchanged examples and sort
those that show expansions to the end of the list.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
new
---
 Documentation/revisions.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index ac7dd8e..8d65986 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -329,14 +329,14 @@ Revision Range Summary
 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
+   D                      G H D
+   D F                    G H I J D F
+   ^G D                   H D
+   ^D B                   E I J F B
+   ^D B C                 E I J F B C
+   C                      I J F 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^@    = C^1
           = F             I J F
    B^@    = B^1 B^2 B^3
-- 
2.9.0.windows.1

Re: [PATCH v5 00/12] Update git revisions

[Marc Branchaud]

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!

		M.

Re: [PATCH v5 00/12] Update git revisions

[Philip Oakley]

From: "Marc Branchaud" <marcnarc@xiplink.com>
> 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!

No, that's fine. It's important to at least review these points.

I thought I'd picked up all the issues, but it looks like I missed at least 
one.

The caret thing has a bit of history - see 87c6aeb4efdd43559

It looks like its the two carets on a line mean superscript (Unconstrained 
quotes) and that maybe the issue.

Then it looks like {caret} does a replacement, though I can't find that in 
the asciidoc user guide.


I don't quite understand why the ^ symbols work for the Loliger examples, 
but hey ho, it's good they do...

I'll work on the tweaks, though it'll probably be tomorrow as we have 
visitors.

--
Philip 

Re: [PATCH v5 00/12] Update git revisions

[Junio C Hamano]

"Philip Oakley" <philipoakley@iee.org> writes:

> I'll work on the tweaks, though it'll probably be tomorrow as we have
> visitors.

Thank you for working on this; Marc, thank you for many good review
comments.

Re: name for A..B ranges?

[Junio C Hamano]

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

Re: name for A..B ranges?

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> "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.

Hi Junio

I'm not sure what's meant here. That patch was about ensuring that the 
relevant syntax notations had headings to make them more easily locatable, 
not to change the explanations.

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

I felt the explanations, once found, were OK. It was the discovery step I 
was hoepfully addressing.
>
>> 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.

Rather than trying to find a complement to the previously invented 
"symmetric difference" name (for the section heading), 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".

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?

--
Philip

Re: name for A..B ranges?

[Junio C Hamano]

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

Re: name for A..B ranges?

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> "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.
> --

Thanks, I'll update the patches (probably tomorrow)
Philip