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

From: Jakub Narębski <jnareb@gmail.com>
Date: Aug 29, 2016, 14:43 UTC
Message-ID: <557eb782-ee45-3e33-33bb-aa88817dcd82@gmail.com>
In-Reply-To: <EDA7BA88AB1D42C7B4228D71CC28145B@PhilipOakley>

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.

[...]

Show 16 quoted lines

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