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

["Philip Oakley" <philipoakley@iee.org>]

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