From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Juanma Barranquero Newsgroups: gmane.emacs.devel Subject: Re: master 1d4862e: Fix English grammar in some doc strings and comments Date: Fri, 8 Nov 2019 05:24:59 +0100 Message-ID: References: <14407.1572888070@quatro> <8736f3js95.fsf@fastmail.fm> <871runxqjq.fsf@gmx.net> <87eeyj8nqr.fsf@gnus.org> <9ccae76c-07a2-1739-d4b0-5c13164145d3@cs.ucla.edu> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="0000000000004a42db0596ce2c56" Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="245026"; mail-complaints-to="usenet@blaine.gmane.org" Cc: Lars Ingebrigtsen , Emacs developers To: Paul Eggert Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Nov 08 05:25:43 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iSvqB-0011fS-IJ for ged-emacs-devel@m.gmane.org; Fri, 08 Nov 2019 05:25:43 +0100 Original-Received: from localhost ([::1]:49716 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iSvqA-0002bK-DB for ged-emacs-devel@m.gmane.org; Thu, 07 Nov 2019 23:25:42 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:42397) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iSvq4-0002bD-Lv for emacs-devel@gnu.org; Thu, 07 Nov 2019 23:25:37 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iSvq3-0003TH-Lh for emacs-devel@gnu.org; Thu, 07 Nov 2019 23:25:36 -0500 Original-Received: from mail-qv1-xf2b.google.com ([2607:f8b0:4864:20::f2b]:46481) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iSvq3-0003Sz-GC for emacs-devel@gnu.org; Thu, 07 Nov 2019 23:25:35 -0500 Original-Received: by mail-qv1-xf2b.google.com with SMTP id w11so1703492qvu.13 for ; Thu, 07 Nov 2019 20:25:34 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=bzYubogLg+3XZe1MNluWlrH/f+A2OirOzAUeI7uWWa8=; b=DNKzcA9apHVMsB0elbbKO2pNVXV+4/bAxvrknqRAzKaLsy+cIOXcO15Ep9hRPIwDUB LcE6vMyoH7++IYpyzmUpdb3r1p/bGHP1uo18NG6BcrERtxlAY490cE3z4AtnaZZBOUrP o4ctr+MZEKooejqM/uVMIG62SzsJaWinztTUhKXYliaNTqfCfvPZfKBN8mkcNTCKJBqg X0NpuYZVzPqVQhsG8ouQCjfhfSzpYtuUyvHxe8h0813kVR7f1SUNa8veHBa0zjz0jtuC dBzXtCu5Ve0xKmLUQ+fBxH72MD31SabmOLrR3uqjK0G8c4O8AzavcPeVP/wONLdPa+2V wr/Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=bzYubogLg+3XZe1MNluWlrH/f+A2OirOzAUeI7uWWa8=; b=Hb52MYuO7YbxKe+oTbhFJEP2EoN5rkf0UIgSLE4sX/BWgK0S/Qzo+GY4GNmkGjrFnv Qjri2A3ouhRrDORETYMTAqKccPn+qvXZy1TUhdUjyjSXBRuWbiiluI5PCDlC7WMq9QvT iI5VKNbZvrZuA2wMYW2BTwmtRK2yWJH1Ga/OGSF2ljcOdlng/SYcPKtx8CJTbK0NyFHg /uH7cCnJOQR+utleRFIacUkc1W5egVxpODKDRJ48Cc3wZ6zqK4H7BU67qyWi3ZGMF19j KMSfSBPiioxIESCAMYzwaEYaFhPaycuYq0ONSDufQyYAhogHWhI/BjecLRIxOD8nz+1c RH7A== X-Gm-Message-State: APjAAAWSSXVxiiflWcc6xZHTu7OdjHWFuRMysJxYBuWfGetUlX/zrXLX nAovpfn6HxFAaoFmN2gl5Ndcl4S+JE3P7oPrZVw= X-Google-Smtp-Source: APXvYqy0Og7uUu4Au7hv6qgbNok3n4a3BSVDx+ZwNkJ94gKZLthG0yhRYNJZKtUKoBysGxdEcgR4geaqJmfQJ2wwHKA= X-Received: by 2002:ad4:482d:: with SMTP id h13mr7619032qvy.68.1573187134045; Thu, 07 Nov 2019 20:25:34 -0800 (PST) In-Reply-To: <9ccae76c-07a2-1739-d4b0-5c13164145d3@cs.ucla.edu> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2607:f8b0:4864:20::f2b X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:241965 Archived-At: --0000000000004a42db0596ce2c56 Content-Type: text/plain; charset="UTF-8" On Fri, Nov 8, 2019 at 4:36 AM Paul Eggert 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". --0000000000004a42db0596ce2c56 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable

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.=C2=A0

there's no additional clarity. It c= ould also be argued that, in those cases where the result is less natural-s= ounding it diminishes clarity, because it increases the cognitive load, eve= n if slightly so.

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

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

> but then someone el= se who reads the sentence will
> internally vocalize it differently a= nd misinterpret the scope of the
> "only".

We don't see a deluge of bug reports about misunderstanding th= e docs because of some (allegedly) misplaced "only".
--0000000000004a42db0596ce2c56--