[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: master 1d4862e: Fix English grammar in some doc strings and comments
From: |
Paul Eggert |
Subject: |
Re: master 1d4862e: Fix English grammar in some doc strings and comments |
Date: |
Thu, 7 Nov 2019 19:35:35 -0800 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.2.0 |
On 11/7/19 11:55 AM, Lars Ingebrigtsen wrote:
I doubt anybody, non native speaker or not, would find the former
ambiguous. The change is simply nonsensical pet peeving.
Pet peeving yes, nonsensical no. In many cases this sort of change does
improve clarity, and it's a good habit to use the word "only"
consistently to lessen the probability of misunderstanding, as there's
little harm in following what you're calling a "pet peeve" guideline and
there can often be a benefit in doing so.
For example, here's one of the changes Stephen installed:
-If the value is `after-completion', confirmation is only
- requested if the user called `minibuffer-complete' right before
+If the value is `after-completion', confirmation is requested
+ only if the user called `minibuffer-complete' right before
`minibuffer-complete-and-exit'.
This particular change makes it less likely that a reader will
misinterpret the doc string as saying that confirmation is *requested*
instead of being *required*.
In verbal communication, it's less important to follow the "pet peeve"
guideline for "only", as vocal emphasis often makes it clear which
meaning is intended. Written communication lacks this advantage, though.
Worse, the writer of a sentence often internally vocalizes it and
naturally thinks "well, there's only one plausible way to interpret this
so it's good enough", but then someone else who reads the sentence will
internally vocalize it differently and misinterpret the scope of the
"only". So when writing technical documentation it's a good habit to
follow the "pet peeve" guideline even when the sentence seems
unambiguous to you otherwise.
(If you're writing love letters, the rules are of course quite different
and you can disregard this email. :-)
- Re: master 1d4862e: Fix English grammar in some doc strings and comments, Juanma Barranquero, 2019/11/04
- Re: master 1d4862e: Fix English grammar in some doc strings and comments, Stephen Gildea, 2019/11/04
- Re: master 1d4862e: Fix English grammar in some doc strings and comments, Joost Kremers, 2019/11/04
- Re: master 1d4862e: Fix English grammar in some doc strings and comments, Juanma Barranquero, 2019/11/04
- Re: master 1d4862e: Fix English grammar in some doc strings and comments, Stephen Berman, 2019/11/04
- Re: master 1d4862e: Fix English grammar in some doc strings and comments, Juanma Barranquero, 2019/11/04
- Re: master 1d4862e: Fix English grammar in some doc strings and comments, Richard Stallman, 2019/11/05
- Re: master 1d4862e: Fix English grammar in some doc strings and comments, Juanma Barranquero, 2019/11/07
- Re: master 1d4862e: Fix English grammar in some doc strings and comments, Richard Stallman, 2019/11/07
- Re: master 1d4862e: Fix English grammar in some doc strings and comments, Lars Ingebrigtsen, 2019/11/07
- Re: master 1d4862e: Fix English grammar in some doc strings and comments,
Paul Eggert <=
- Re: master 1d4862e: Fix English grammar in some doc strings and comments, Juanma Barranquero, 2019/11/07
- Re: master 1d4862e: Fix English grammar in some doc strings and comments, Paul Eggert, 2019/11/08
- Re: master 1d4862e: Fix English grammar in some doc strings and comments, Juanma Barranquero, 2019/11/08
- Re: master 1d4862e: Fix English grammar in some doc strings and comments, Lars Ingebrigtsen, 2019/11/07
- Re: master 1d4862e: Fix English grammar in some doc strings and comments, Richard Stallman, 2019/11/08