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

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

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