Re: [PATCH v5 09/12] doc: revisions - define `reachable`
From: "Jakub Narębski" W dniu 29.08.2016 o 15:21, Philip Oakley pisze: From: "Jakub Narębski" 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
Re: [PATCH v5 09/12] doc: revisions - define `reachable`
W dniu 29.08.2016 o 15:21, Philip Oakley pisze: > From: "Jakub Narębski" > 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`
From: "Jakub Narębski" 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`
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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
