Re: master 1d4862e: Fix English grammar in some doc strings and comments

Re: master 1d4862e: Fix English grammar in some doc strings and comments

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 745 bytes --]

On Mon, Nov 4, 2019 at 3:38 AM Stephen Gildea <stepheng+savannah@gildea.com>
wrote:

> -In this case, we try to ignore minor-modes, and only return a
> +In this case, we try to ignore minor-modes, and return only a

> -Only used by `save-buffer'."
> +Used only by `save-buffer'."

> -This function only handles buffers that are visiting files.
> +This function handles only buffers that are visiting files.

> -This variable only applies to buffers where `buffer-file-name' is
> +This variable applies only to buffers where `buffer-file-name' is

> -This function only handles buffers that are visiting files.
> +This function handles only buffers that are visiting files.

Just out of curiosity, in what sense is that "fixing a grammar error"?

[-- Attachment #2: Type: text/html, Size: 990 bytes --]

Re: master 1d4862e: Fix English grammar in some doc strings and comments

[Stephen Gildea]

>   On Mon, Nov 4, 2019 at 3:38 AM Stephen Gildea <stepheng+savannah@gildea.com>
>   wrote:
>   
>   > -In this case, we try to ignore minor-modes, and only return a
>   > +In this case, we try to ignore minor-modes, and return only a
>   
>   > -Only used by `save-buffer'."
>   > +Used only by `save-buffer'."
>   
>   > -This function only handles buffers that are visiting files.
>   > +This function handles only buffers that are visiting files.
>   
>   > -This variable only applies to buffers where `buffer-file-name' is
>   > +This variable applies only to buffers where `buffer-file-name' is
>   
>   > -This function only handles buffers that are visiting files.
>   > +This function handles only buffers that are visiting files.
>   
>   Just out of curiosity, in what sense is that "fixing a grammar error"?

As a limiting adverb, "only" must be placed next to the thing it limits.
For example, in the last sentence you quote, "only" does not limit what
the function does with the buffers (handle them) but rather limits what
is handled (file-visiting buffers).

Thank you for asking about limiting adverbs,

 < Stephen

Re: master 1d4862e: Fix English grammar in some doc strings and comments

[Joost Kremers]

On Mon, Nov 04 2019, Stephen Gildea wrote:
>>   On Mon, Nov 4, 2019 at 3:38 AM Stephen Gildea 
>>   <stepheng+savannah@gildea.com>
>>   wrote:
>>   
>>   > -In this case, we try to ignore minor-modes, and only 
>>   > return a
>>   > +In this case, we try to ignore minor-modes, and return 
>>   > only a
>>   
>>   > -Only used by `save-buffer'."
>>   > +Used only by `save-buffer'."
>>   
>>   > -This function only handles buffers that are visiting 
>>   > files.
>>   > +This function handles only buffers that are visiting 
>>   > files.
>>   
>>   > -This variable only applies to buffers where 
>>   > `buffer-file-name' is
>>   > +This variable applies only to buffers where 
>>   > `buffer-file-name' is
>>   
>>   > -This function only handles buffers that are visiting 
>>   > files.
>>   > +This function handles only buffers that are visiting 
>>   > files.
>>   
>>   Just out of curiosity, in what sense is that "fixing a 
>>   grammar error"?
>
> As a limiting adverb, "only" must be placed next to the thing it 
> limits.
> For example, in the last sentence you quote, "only" does not 
> limit what
> the function does with the buffers (handle them) but rather 
> limits what
> is handled (file-visiting buffers).

Says who? The original examples all sound perfectly natural, more 
natural than the corrections, in fact. Looks like one of those 
rules up with which we should not put.


-- 
Joost Kremers
Life has its moments

Re: master 1d4862e: Fix English grammar in some doc strings and comments

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 627 bytes --]

On Mon, Nov 4, 2019 at 9:34 PM Joost Kremers <joostkremers@fastmail.fm>
wrote:

> Says who? The original examples all sound perfectly natural, more
> natural than the corrections, in fact. Looks like one of those
> rules up with which we should not put.

My thoughts exactly. That seems like the kind of prescriptivist "rule" out
of Strunk & White and the like, blindly and eagerly adopted by style
guide's writers everywhere, but not based in any objective fact about the
English language. Like the idea that you shouldn't split infinitives, or
end sentences with prepositions, and passive must be avoided at almost any
cost.

[-- Attachment #2: Type: text/html, Size: 759 bytes --]

Re: master 1d4862e: Fix English grammar in some doc strings and comments

[Stephen Berman]

On Mon, 4 Nov 2019 22:37:41 +0100 Juanma Barranquero <lekktu@gmail.com> wrote:

> On Mon, Nov 4, 2019 at 9:34 PM Joost Kremers <joostkremers@fastmail.fm> wrote:
>
>> Says who? The original examples all sound perfectly natural, more
>> natural than the corrections, in fact. Looks like one of those
>> rules up with which we should not put.
>
> My thoughts exactly. That seems like the kind of prescriptivist "rule"
> out of Strunk & White and the like, blindly and eagerly adopted by
> style guide's writers everywhere, but not based in any objective fact
> about the English language. Like the idea that you shouldn't split
> infinitives, or end sentences with prepositions, and passive must be
> avoided at almost any cost.

The following passage from _The Cambridge Grammar of the English
Language_ (Huddleston, Pullum, et al., (c) 2002, pp590-591) is apropos:

  When /only/ precedes the focus and the latter is contained within the
  VP, /only/ is commonly non-adjacent, functioning syntactically as
  modifier to the whole VP, as in [We only found one mistake].  There is
  a long-standing prescriptive tradition of condemning this construction
  and saying that in writing /only/ should be placed immediately before
  its focus. It is recognised that one needs to distinguish here between
  speech and writing, because in speech the focus will usually be
  prosodically marked (as noted above, the scopal focus usually
  coincides with the informational focus). In writing, however, there is
  generally no analogue of stress, and hence no comparable way of
  marking the intended focus. For this reason, the prescriptive argument
  goes, the focus should be marked by placing only immediately before
  it.

  This is another of those well-known prescriptive rules that are
  massively at variance with actual usage, including the usage of the
  best writers. The more empirically based manuals recognise this, and
  cite numerous literary examples that violate the rule, such as those
  in [51], where the focus is marked by underlining:

  [51] i I [only saw Granny _at carefully spaced intervals_].
      ii Boris doesn't eat shanks so, of course, I [only cook them _when
         he's away_].

  Examples of this kind are clearly impeccable. There is no grammatical
  rule requiring that /only/ be adjacent to its focus. And all that can
  validly be said from the perspective of style is that the general
  injunction to avoid potential confusion or misinterpretation should be
  respected as usual. In the absence of contextual indications to the
  contrary, /saw/ and /Granny/ in [i] are not plausible candidates for
  the status of focus: it is not necessary therefore to place /only/
  adjacent to the PP to indicate that it is the intended
  focus. Similarly, in [ii], the context provided by the first clause
  together with the connective /so/ makes it obvious that /when he's
  away/ is the intended focus, and it is therefore quite mistaken to
  insist that /only/ must be placed after /cook them/. Such examples may
  be contrasted with those in [52], where there is significantly greater
  potential for misinterpretation, and hence a stronger case for
  recommending that /only/ be placed next to the intended focus:

  [52] i You can only access the web at this workstation.
      ii Last Christmas he only gave money to his children.

  In [i] either /the web/ or /this/ might reasonably be taken as focus,
  yielding an ambiguity between the readings "At this workstation
  accessing the web is all you can do" and "This is the only workstation
  at which you can access the web". And in [ii] both /money/ and
  /children/ might be plausible candidates for focus: "He didn't give
  his children anything execpt or more than money" or "His children were
  the only ones to whom he gave money". But of course, the issue of
  whether there is any realy danger of misinterpretation will dpend on
  the context in which the sentences are used.

Re: master 1d4862e: Fix English grammar in some doc strings and comments

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 456 bytes --]

On Mon, Nov 4, 2019 at 10:47 PM Stephen Berman <stephen.berman@gmx.net>
wrote:

> The following passage from _The Cambridge Grammar of the English
> Language_ (Huddleston, Pullum, et al., (c) 2002, pp590-591) is apropos:

I'm not surprised, because George K. Pullum has an history of exposing (in
the Language Log blog and elsewhere) that kind of prescriptive imposition
as baseless. His tirades against the recommendation to avoid passives are
legendary.

[-- Attachment #2: Type: text/html, Size: 564 bytes --]

Re: master 1d4862e: Fix English grammar in some doc strings and comments

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Such examples may
  >   be contrasted with those in [52], where there is significantly greater
  >   potential for misinterpretation, and hence a stronger case for
  >   recommending that /only/ be placed next to the intended focus:

  >   [52] i You can only access the web at this workstation.
  >       ii Last Christmas he only gave money to his children.

This is the practical reason for being careful where to place "only"
in a written text.

It is true that other positioning for "only" is not inherently wrong.
It merely risks ambiguity.  But avoiding ambiguity is a proper goal
in writing documentation.  Thus, a rule about where to place "only"
may be a wise policy, even though grammar does not exactly require it.


-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: master 1d4862e: Fix English grammar in some doc strings and comments

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 284 bytes --]

On Wed, Nov 6, 2019 at 4:28 AM Richard Stallman <rms@gnu.org> wrote:

> But avoiding ambiguity is a proper goal in writing documentation.

True. But in the case discussed, I suspect most native English speakers
will find the original sentences more natural, and not ambiguous at all.

[-- Attachment #2: Type: text/html, Size: 412 bytes --]

Re: master 1d4862e: Fix English grammar in some doc strings and comments

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > True. But in the case discussed, I suspect most native English speakers
  > will find the original sentences more natural, and not ambiguous at all.

You may be right about that.  But many of the people who read our
manual are not native speakers of English.  The ambiguity may take
some work for them to figure out.

(This is why I object when "they" is used for a singular antecedent.
If there is another possible antecedent which is plural, it takes work
to figure out which meaning is intended.)

-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: master 1d4862e: Fix English grammar in some doc strings and comments

[Lars Ingebrigtsen]

Richard Stallman <rms@gnu.org> writes:

> You may be right about that.  But many of the people who read our
> manual are not native speakers of English.  The ambiguity may take
> some work for them to figure out.

You're right that it's better when things are better, but did you look
at the concrete changes in this case?

Typical example:

> -This variable only applies to buffers where `buffer-file-name' is
> +This variable applies only to buffers where `buffer-file-name' is

I doubt anybody, non native speaker or not, would find the former
ambiguous.  The change is simply nonsensical pet peeving.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: master 1d4862e: Fix English grammar in some doc strings and comments

[Paul Eggert]

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]

[-- Attachment #1: Type: text/plain, Size: 1112 bytes --]

On Fri, Nov 8, 2019 at 4:36 AM Paul Eggert <eggert@cs.ucla.edu> wrote:

> In many cases this sort of change does
> improve clarity,

In some cases, perhaps. In the example you quote, yes, it does perhaps
improve clarity. But here:

> -This function only handles buffers that are visiting files.
> +This function handles only buffers that are visiting files.

there's no additional clarity. It could also be argued that, in those cases
where the result is less natural-sounding it diminishes clarity, because it
increases the cognitive load, even if slightly so.

> and it's a good habit to use the word "only" consistently

Ralph Waldo Emerson's dictum about foolish consistency being the hobgoblin
of little minds has been quoted in this list often enough. If a change
produces a less natural sentence, that should be taken into account over
any "consistency".

> but then someone else who reads the sentence will
> internally vocalize it differently and misinterpret the scope of the
> "only".

We don't see a deluge of bug reports about misunderstanding the docs
because of some (allegedly) misplaced "only".

[-- Attachment #2: Type: text/html, Size: 1652 bytes --]

Re: master 1d4862e: Fix English grammar in some doc strings and comments

[Lars Ingebrigtsen]

Paul Eggert <eggert@cs.ucla.edu> writes:

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

Yes, that's a good change -- and that's not what's being objected to.
It's changes like this that's the problem:

> -This variable only applies to buffers where `buffer-file-name' is
> +This variable applies only to buffers where `buffer-file-name' is

But I know that this is a fruitless discussion: People with pet peeves
feel much more strongly about their peeves than the rest of us who
recognise this for what it is.  We can only roll our eyes when these
changes roll by, and feebly point to experts like Pullum in the hopes
that people will just, like, stop.

But of course they won't.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Re: master 1d4862e: Fix English grammar in some doc strings and comments

[Paul Eggert]

On 11/7/19 8:24 PM, Juanma Barranquero wrote:
>> -This function only handles buffers that are visiting files.
>> +This function handles only buffers that are visiting files.

> there's no additional clarity. It could also be argued that, in those cases
> where the result is less natural-sounding it diminishes clarity,

I'm not aware of any such cases. To my ear, the revised text in the example you 
gave is just as natural-sounding as the original. I agree that we shouldn't be 
pedantic about "only" in places where that would reduce clarity.

I'm willing to put up with these less-important changes, if consistent use of 
the style helps to fix confusion elsewhere (as that patch did). It's akin to 
preferring signed to unsigned arithmetic in C code - even in places where this 
makes no real difference - because being reasonably consistent about preferring 
signed arithmetic helps makes Emacs more reliable overall.

Re: master 1d4862e: Fix English grammar in some doc strings and comments

[Juanma Barranquero]

[-- Attachment #1: Type: text/plain, Size: 808 bytes --]

On Fri, Nov 8, 2019 at 10:31 PM Paul Eggert <eggert@cs.ucla.edu> wrote:

> I'm not aware of any such cases. To my ear, the revised text in the
example you
> gave is just as natural-sounding as the original.

I'm not a native English speaker, but some have chimed in already about the
naturalness of some of these changes.

> I'm willing to put up with these less-important changes, if consistent
use of
> the style helps to fix confusion elsewhere (as that patch did).

Yes, that's obviously your position in this discussion. I think the patch
introduced some good changes, and others that didn't do anything to improve
the docs and were just personal preferences.

That's why I started this thread asking why (some of) these changes were
"grammar fixes". They weren't. Not my opinion: the experts' opinion.

[-- Attachment #2: Type: text/html, Size: 980 bytes --]

Re: master 1d4862e: Fix English grammar in some doc strings and comments

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > -This variable only applies to buffers where `buffer-file-name' is
  > > +This variable applies only to buffers where `buffer-file-name' is

  > I doubt anybody, non native speaker or not, would find the former
  > ambiguous.  The change is simply nonsensical pet peeving.

Maybe you are right.  I was talking about the general point, not
this specific case.

-- 
Dr Richard Stallman
Founder, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)