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

classic Classic list List threaded Threaded
16 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Juanma Barranquero

On Mon, Nov 4, 2019 at 3:38 AM Stephen Gildea <[hidden email]> 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"?
Reply | Threaded
Open this post in threaded view
|

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

Stephen Gildea-3
>   On Mon, Nov 4, 2019 at 3:38 AM Stephen Gildea <[hidden email]>
>   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

Reply | Threaded
Open this post in threaded view
|

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

Joost Kremers-2

On Mon, Nov 04 2019, Stephen Gildea wrote:

>>   On Mon, Nov 4, 2019 at 3:38 AM Stephen Gildea
>>   <[hidden email]>
>>   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

Reply | Threaded
Open this post in threaded view
|

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

Juanma Barranquero
On Mon, Nov 4, 2019 at 9:34 PM Joost Kremers <[hidden email]> 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.

Reply | Threaded
Open this post in threaded view
|

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 <[hidden email]> wrote:

> On Mon, Nov 4, 2019 at 9:34 PM Joost Kremers <[hidden email]> 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.

Reply | Threaded
Open this post in threaded view
|

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

Juanma Barranquero
On Mon, Nov 4, 2019 at 10:47 PM Stephen Berman <[hidden email]> 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.
Reply | Threaded
Open this post in threaded view
|

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

Richard Stallman
In reply to this post by Stephen Berman
[[[ 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)



Reply | Threaded
Open this post in threaded view
|

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

Juanma Barranquero


On Wed, Nov 6, 2019 at 4:28 AM Richard Stallman <[hidden email]> 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.

Reply | Threaded
Open this post in threaded view
|

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)



Reply | Threaded
Open this post in threaded view
|

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

Lars Ingebrigtsen
Richard Stallman <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

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. :-)

Reply | Threaded
Open this post in threaded view
|

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

Juanma Barranquero

On Fri, Nov 8, 2019 at 4:36 AM Paul Eggert <[hidden email]> 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".

Reply | Threaded
Open this post in threaded view
|

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

Lars Ingebrigtsen
In reply to this post by Paul Eggert
Paul Eggert <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

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

Paul Eggert
In reply to this post by Juanma Barranquero
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.

Reply | Threaded
Open this post in threaded view
|

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

Juanma Barranquero

On Fri, Nov 8, 2019 at 10:31 PM Paul Eggert <[hidden email]> 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.

Reply | Threaded
Open this post in threaded view
|

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

Richard Stallman
In reply to this post by Lars Ingebrigtsen
[[[ 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)