Re: [PATCH v2] doc: clarify that "git bisect" accepts one or more good commits

["Robert P. J. Day" <rpjday@crashcourse.ca>]

On Fri, 24 Nov 2017, Junio C Hamano wrote:

> "Robert P. J. Day" <rpjday@crashcourse.ca> writes:

... snip ...

> > -to indicate that it was after.
> > +to indicate a single commit after that change.
>
> As to "identify", I would say it is better to consistently use
> "indicate" like the original of these two hunks at the end says,
> i.e. "indicate that it is bad/new (or they are good/old)".

  i'm going to ponder this, but let me explain why i am such an
annoying stickler for the choice of words at times, and you can read
all about it here:

  http://twain.lib.virginia.edu/projects/rissetto/offense.html

in particular, i draw your attention to twain's trashing of cooper
for, in many cases, using *almost* the right word, but not *quite* the
right word:

"Cooper's word-sense was singularly dull. When a person has a poor ear
for music he will flat and sharp right along without knowing it. He
keeps near the tune, but is not the tune. When a person has a poor ear
for words, the result is a literary flatting and sharping; you
perceive what he is intending to say, but you also perceive that he
does not say it. This is Cooper. He was not a word-musician. His ear
was satisfied with the approximate words. I will furnish some
circumstantial evidence in support of this charge. My instances are
gathered from half a dozen pages of the tale called "Deerslayer." He
uses "Verbal" for "oral"; "precision" for "facility"; "phenomena" for
"marvels"; "necessary" for "predetermined"; "unsophisticated" for
"primitive"; "preparation" for "expectancy"; "rebuked" for "subdued";
"dependent on" for "resulting from"; "fact" for "condition"; "fact"
for "conjecture"; "precaution" for "caution"; "explain" for
"determine"; "mortified" for "disappointed"; "meretricious" for
"factitious"; "materially" for "considerably"; "decreasing" for
"deepening"; "increasing" for "disappearing"; "embedded" for
"inclosed"; "treacherous" for "hostile"; "stood" for "stooped";
"softened" for "replaced"; "rejoined" for "remarked"; "situation" for
"condition"; "different" for "differing"; "insensible" for
"unsentient"; "brevity" for "celerity"; "distrusted" for "suspicious";
"mental imbecility" for "imbecility"; "eyes" for "sight";
"counteracting" for "opposing"; "funeral obsequies" for "obsequies."

  in this sense, i don't think "indicate" and "identify" are
completely interchangeable. in my mind, the word "identify" does
nothing more than, you know, point at something and say, "that one,
that's the one i'm talking about;" it goes no further than that.

  on the other hand, the word "indicate" (in my mind) implies that
you're about to provide some *property* or *quality* of something, and
you do exactly that in the earlier quote:

> As to "identify", I would say it is better to consistently use
> "indicate" like the original of these two hunks at the end says,
> i.e. "indicate that it is bad/new (or they are good/old)".

  as in, you "identify" a commit, but you "indicate" that it
represents a good or bad commit. i know this sounds picky, but it is
exactly this tendency of using *almost* the right word that makes a
lot of documentation potentially confusing. given this distinction,
depending on the word to be used, i would write one of:

1) "first, identify the bad commit and one or more good commits..."

2) "first, indicate which commit is the bad commit, and which commits
are the good commits ..."

  the eventual meaning *should* be the same, but the choice of words
can make the meaning clear, or can confuse the reader.

  thoughts?

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================