From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#24979: 24.5; Doc string of `current-word' Date: Fri, 25 Nov 2016 07:36:27 -0800 (PST) Message-ID: <759faee5-8fa2-45a1-bee1-df2df096cb75@default> References: <> <<83fumf51k7.fsf@gnu.org>> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1480088231 16590 195.159.176.226 (25 Nov 2016 15:37:11 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Fri, 25 Nov 2016 15:37:11 +0000 (UTC) Cc: 24979-done@debbugs.gnu.org To: Eli Zaretskii , Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Nov 25 16:37:07 2016 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cAIYl-0003dG-CR for geb-bug-gnu-emacs@m.gmane.org; Fri, 25 Nov 2016 16:37:07 +0100 Original-Received: from localhost ([::1]:46750 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cAIYo-0000of-JH for geb-bug-gnu-emacs@m.gmane.org; Fri, 25 Nov 2016 10:37:10 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:32842) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cAIYj-0000oP-2C for bug-gnu-emacs@gnu.org; Fri, 25 Nov 2016 10:37:06 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cAIYf-0001xk-Vw for bug-gnu-emacs@gnu.org; Fri, 25 Nov 2016 10:37:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:54448) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cAIYf-0001xf-SZ for bug-gnu-emacs@gnu.org; Fri, 25 Nov 2016 10:37:01 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1cAIYf-0005KG-Mn for bug-gnu-emacs@gnu.org; Fri, 25 Nov 2016 10:37:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 25 Nov 2016 15:37:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 24979 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 24979-done@debbugs.gnu.org id=D24979.148008819920444 (code D ref 24979); Fri, 25 Nov 2016 15:37:01 +0000 Original-Received: (at 24979-done) by debbugs.gnu.org; 25 Nov 2016 15:36:39 +0000 Original-Received: from localhost ([127.0.0.1]:41614 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cAIYJ-0005Jg-6F for submit@debbugs.gnu.org; Fri, 25 Nov 2016 10:36:39 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:20821) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cAIYG-0005JQ-Lc for 24979-done@debbugs.gnu.org; Fri, 25 Nov 2016 10:36:37 -0500 Original-Received: from userv0022.oracle.com (userv0022.oracle.com [156.151.31.74]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id uAPFaUPp019528 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 25 Nov 2016 15:36:30 GMT Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by userv0022.oracle.com (8.14.4/8.14.4) with ESMTP id uAPFaTDB030228 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Fri, 25 Nov 2016 15:36:30 GMT Original-Received: from abhmp0011.oracle.com (abhmp0011.oracle.com [141.146.116.17]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id uAPFaSsq013214; Fri, 25 Nov 2016 15:36:29 GMT In-Reply-To: <<83fumf51k7.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 12.0.6753.5000 (x86)] X-Source-IP: userv0022.oracle.com [156.151.31.74] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:126089 Archived-At: > > This part of the doc string is wrong: > > > > The function, belying its name, normally finds a symbol. > > > > > > 1. There is no "normally". Do you mean often? Usually? > > Sometimes? (When?) >=20 > "Normally" is GNU and Emacs parlance for "by default", and is > usually (as in this case) followed by the description of the > non-default use case. You will find gazillions of this in > the documentation. If there are other cases where "normally" is used to convey "by default" then I hope they get fixed too. If the surrounding text makes clear, e.g. by explicitly contrasting, that what is meant by "normally" is the default case, then it could be OK (but should never be _preferred_ to stating clearly and explicitly what the default behavior is). In this case, "normally" might have been able to be understood the way you say if the last two sentences were in their own paragraph, so that the last more clearly qualified the statement of the next-to-last, instead of appearing to stand on its own. > I think this is splitting hair, probably because "symbol" is > ambiguous due to its being a Lisp object. E.g., if the doc > string said > Return the word at or near point, as a string. > you wouldn't object, because "word" is not a Lisp object. Correct. I wouldn't have objected about calling it a word. But I would have objected about "near", which is not the same as on-the-same-line-and-adjacent-to - it is quite different, in fact. > Anyway, I modified the doc string to say >=20 > "Return the word at or near point, as a string. Return the word at point or adjacent to it, as a string. (or a bit less clear: Return the word at or adjacent to point, as a string.) See above. The rest looks good. Thx.