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

[Juanma Barranquero <lekktu@gmail.com>]

[-- 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 --]