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

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

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

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

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