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#25428: 25.1; Incorrect doc string for `delete-selection-mode' Date: Wed, 16 Aug 2017 20:25:31 -0700 (PDT) Message-ID: <2e0430c1-4783-4b53-ac95-300282a1a6be@default> References: <87efsbrm9u.fsf@moondust.localdomain> 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 1502940438 32184 195.159.176.226 (17 Aug 2017 03:27:18 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Thu, 17 Aug 2017 03:27:18 +0000 (UTC) Cc: 25428@debbugs.gnu.org To: nljlistbox2@gmail.com Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Thu Aug 17 05:27:14 2017 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 1diBSe-0007p6-2r for geb-bug-gnu-emacs@m.gmane.org; Thu, 17 Aug 2017 05:27:08 +0200 Original-Received: from localhost ([::1]:51658 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1diBSk-0003ZY-GA for geb-bug-gnu-emacs@m.gmane.org; Wed, 16 Aug 2017 23:27:14 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47134) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1diBSd-0003Yd-AC for bug-gnu-emacs@gnu.org; Wed, 16 Aug 2017 23:27:08 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1diBSY-0006rE-Ce for bug-gnu-emacs@gnu.org; Wed, 16 Aug 2017 23:27:07 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:33109) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1diBSY-0006r8-9V for bug-gnu-emacs@gnu.org; Wed, 16 Aug 2017 23:27:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1diBSX-0004qr-U8 for bug-gnu-emacs@gnu.org; Wed, 16 Aug 2017 23:27:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 17 Aug 2017 03:27:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 25428 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 25428-submit@debbugs.gnu.org id=B25428.150294037318593 (code B ref 25428); Thu, 17 Aug 2017 03:27:01 +0000 Original-Received: (at 25428) by debbugs.gnu.org; 17 Aug 2017 03:26:13 +0000 Original-Received: from localhost ([127.0.0.1]:41790 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1diBRl-0004pp-98 for submit@debbugs.gnu.org; Wed, 16 Aug 2017 23:26:13 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:27589) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1diBRj-0004pb-Ja for 25428@debbugs.gnu.org; Wed, 16 Aug 2017 23:26:12 -0400 Original-Received: from userv0021.oracle.com (userv0021.oracle.com [156.151.31.71]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id v7H3Q452003740 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 17 Aug 2017 03:26:05 GMT Original-Received: from userv0122.oracle.com (userv0122.oracle.com [156.151.31.75]) by userv0021.oracle.com (8.14.4/8.14.4) with ESMTP id v7H3Q4xo008777 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 17 Aug 2017 03:26:04 GMT Original-Received: from abhmp0006.oracle.com (abhmp0006.oracle.com [141.146.116.12]) by userv0122.oracle.com (8.14.4/8.14.4) with ESMTP id v7H3Q3kr020804; Thu, 17 Aug 2017 03:26:04 GMT In-Reply-To: <87efsbrm9u.fsf@moondust.localdomain> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 12.0.6774.5000 (x86)] X-Source-IP: userv0021.oracle.com [156.151.31.71] 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:135855 Archived-At: Let's just say that the doc string is incomplete and can easily mislead. If it says anything about interactive behavior (and it should) then it should say just what the description of `define-minor-mode' says for minor modes. If it says anything about the behavior when called from Lisp (and it should) then it should say just what the d-m-m description says. This (i.e., _all_ of the d-m-m description) is missing from the d-s-m doc string: * `toggle' toggles * non-positive integer disables * anything else enables The only bit of info you get about Lisp behavior is that nil/absent enables - part of the "anything else". Yes, the doc string does not say that (d-s-m t) disables. But a cursory reading of this: "If called from Lisp, enable the mode if ARG is omitted or nil." can give that impression. Sure, it says "if" and not "only if", but we all know that may people will understand "only if" or "if and only if". [And you can see that explicitly in the thread of bug #25435: after reading such a description the filer thought it implied that passing `off' should turn it off. To which the snarky reply was to belittle the filer's sense telling him: "Surely common sense tells you that is the intended meaning? There are about 130 instances of this form in Emacs. There are 4 instances of ", also enable", maybe you prefer that? Feel feel to correct them all, I guess, if it bothers you that much. :)"] And as I said in the thread for bug #13926: "This makes no connection between the interactive prefix arg and the arg when called from Lisp. In particular, it can also give the incorrect impression that the mode is enabled ONLY if ARG is omitted or nil. There is nothing that suggests the behavior of a non-positive or positive ARG when called from Lisp." It is also misleading for the doc string to talk about ARG as if it were the prefix arg. Right away that is going to feed confusion: absence of a prefix arg toggles, but in Lisp absence of ARG enables. Rather than the doc making clear the difference between prefix arg interactively and ARG from Lisp, it seems to go out of its way to confuse the two, saying "With a prefix ARG" instead of "With a prefix arg" (or better, "prefix argument"). Better still would be to name the parameter something else than ARG, to avoid just such confusion. The behavior of minor-mode arguments is complex enough, without bad doc to confuse things further. It really should be clear by now that clearer doc is needed about the behavior of minor-mode arguments (and there continue to be questions and confusions about on reddit, stackexchange, etc.). How hard is it get this right now, especially when writing new doc strings? The point is that there is no reason to say anything different for this than what is true for all minor modes and what is said in the doc for d-m-m. No, a user of a minor-mode function should not need to read the doc of d-m-m to obtain info about its behavior. Yes, each command should have a doc string that describes its behavior: (1) interactively and (2) via Lisp. (And if a command is not intended for use from Lisp then that should be stated explicitly.) Do I think that it would be sufficient for every command defined with d-m-m to have a link to the doc string of d-m-m? It would be OK, I think. But barring that, each minor-mode doc string needs to stand on its own and provide that same info - not something partial or misleading.