From debbugs-submit-bounces@debbugs.gnu.org Thu Jan 12 11:25:04 2017 Received: (at submit) by debbugs.gnu.org; 12 Jan 2017 16:25:04 +0000 Received: from localhost ([127.0.0.1]:51729 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cRiBT-0001n9-NI for submit@debbugs.gnu.org; Thu, 12 Jan 2017 11:25:03 -0500 Received: from eggs.gnu.org ([208.118.235.92]:54177) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cRiBQ-0001ma-2P for submit@debbugs.gnu.org; Thu, 12 Jan 2017 11:25:02 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cRiBJ-0007uA-53 for submit@debbugs.gnu.org; Thu, 12 Jan 2017 11:24:55 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=0.8 required=5.0 tests=BAYES_50 autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:52684) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1cRiBJ-0007tj-1P for submit@debbugs.gnu.org; Thu, 12 Jan 2017 11:24:53 -0500 Received: from eggs.gnu.org ([2001:4830:134:3::10]:45122) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cRiBH-0005bf-3Y for bug-gnu-emacs@gnu.org; Thu, 12 Jan 2017 11:24:52 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cRiBC-0007iH-4C for bug-gnu-emacs@gnu.org; Thu, 12 Jan 2017 11:24:51 -0500 Received: from userp1040.oracle.com ([156.151.31.81]:33713) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1cRiBB-0007bf-QV for bug-gnu-emacs@gnu.org; Thu, 12 Jan 2017 11:24:46 -0500 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 v0CGOg0j008626 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Thu, 12 Jan 2017 16:24:43 GMT 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 v0CGOfEX031778 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Thu, 12 Jan 2017 16:24:42 GMT Received: from abhmp0008.oracle.com (abhmp0008.oracle.com [141.146.116.14]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id v0CGOet4027984 for ; Thu, 12 Jan 2017 16:24:41 GMT MIME-Version: 1.0 Message-ID: Date: Thu, 12 Jan 2017 08:24:39 -0800 (PST) From: Drew Adams To: bug-gnu-emacs@gnu.org Subject: 25.1; Incorrect doc string for `delete-selection-mode' X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 12.0.6753.5000 (x86)] Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Source-IP: userv0022.oracle.com [156.151.31.74] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -4.0 (----) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -4.0 (----) The doc string says this: If called from Lisp, enable the mode if ARG is omitted or nil. That is completely wrong. This is an ordinary minor mode, defined using `define-minor-mode', whose doc string says this: When called from Lisp, the mode command toggles the mode if the argument is =E2=80=98toggle=E2=80=99, disables the mode if the argument is= a non-positive integer, and enables the mode otherwise (including if the argument is omitted or nil or a positive integer). E.g., `(delete-selection-mode t)' ENABLES the mode, even though the `delete-selection-mode' doc string says that it DISABLES it. In GNU Emacs 25.1.1 (x86_64-w64-mingw32) of 2016-09-17 built on LAPHROAIG Windowing system distributor 'Microsoft Corp.', version 6.1.7601 Configured using: 'configure --without-dbus --without-compress-install CFLAGS=3D-static' From debbugs-submit-bounces@debbugs.gnu.org Fri Jan 13 12:53:31 2017 Received: (at control) by debbugs.gnu.org; 13 Jan 2017 17:53:31 +0000 Received: from localhost ([127.0.0.1]:53130 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cS62d-0004ob-FA for submit@debbugs.gnu.org; Fri, 13 Jan 2017 12:53:31 -0500 Received: from eggs.gnu.org ([208.118.235.92]:44639) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cS62c-0004oO-DQ for control@debbugs.gnu.org; Fri, 13 Jan 2017 12:53:30 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cS62W-0006wL-Fp for control@debbugs.gnu.org; Fri, 13 Jan 2017 12:53:25 -0500 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-5.1 required=5.0 tests=BAYES_00,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:41979) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cS62W-0006w9-D1 for control@debbugs.gnu.org; Fri, 13 Jan 2017 12:53:24 -0500 Received: from rgm by fencepost.gnu.org with local (Exim 4.82) (envelope-from ) id 1cS62W-000557-37 for control@debbugs.gnu.org; Fri, 13 Jan 2017 12:53:24 -0500 Subject: control message for bug 25434 To: X-Mailer: mail (GNU Mailutils 2.99.98) Message-Id: From: Glenn Morris Date: Fri, 13 Jan 2017 12:53:24 -0500 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -8.2 (--------) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -8.2 (--------) merge 25428 25434 From debbugs-submit-bounces@debbugs.gnu.org Wed Aug 16 21:55:23 2017 Received: (at 25428) by debbugs.gnu.org; 17 Aug 2017 01:55:23 +0000 Received: from localhost ([127.0.0.1]:41760 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1diA1r-0002h4-0d for submit@debbugs.gnu.org; Wed, 16 Aug 2017 21:55:23 -0400 Received: from mail-it0-f65.google.com ([209.85.214.65]:36921) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1diA1p-0002gq-Bs for 25428@debbugs.gnu.org; Wed, 16 Aug 2017 21:55:21 -0400 Received: by mail-it0-f65.google.com with SMTP id 77so3461850itj.4 for <25428@debbugs.gnu.org>; Wed, 16 Aug 2017 18:55:21 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-transfer-encoding; bh=NC3VZsrWw3L59x3SnQ9EnAe9h9ODS3i4OYffGGuuho0=; b=rcJg/bFnp9SurXMzBmAse1Hhq4o2S33f8hnLA076KltFFuRGbF7cK44FpUxYvm7wuO bek9scmgz7yn0IoGXpCupYebXkpO/oIbv/MM9kmsR3K/wJEFVpvBCXoY8Lt24SDuEsVg exurBhVt5kR44fVeCxsmwlb2DleSV4mvBlpClMgrdGoyn732WaBQTgdo2Qj73D9u6DWl pB2/rnxfwP45vPTAePhqXbKrar+31RYL6kmLK6HcWYuPII9N9eE9Bo6r+nGv+sFbtn+y TGP3whhAyGRNifq6V6xAtdMfz52lKdThIVi8rzThsYRwODD67rB2VMeMHSWkY1kCQnl7 UV+w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version:content-transfer-encoding; bh=NC3VZsrWw3L59x3SnQ9EnAe9h9ODS3i4OYffGGuuho0=; b=pCCvhkGLUjsMshG6dhLOVIsIJVjzPvNAZsruIbNnN6YpZLIx82JFWBInITwD6qdcz6 xnnw8DMQ7VwK9dhoAcz9UV8oghCyR88crcXLzay4Zvza47l7/fpItwm760Ep42yldcia fx1tU8npn5KBxBn5Jq4/u9Q3uKXlfNiBIkRhtl4E/a8xjr/KHymCuVnO0Gn7cNT+bcgr 0GL6nNAg//JkX8GSIyOv6+eTbFvX4V4RwNYqHTIhgJWbqcTmKyD8C3c//mnV8ZUpQqGm m7wG4Y9rvsVDvEUsowbkM8YhPEECWGb02vO82TrrxLQjKSbldutDhqJv088Ybg1jl44S PgiQ== X-Gm-Message-State: AHYfb5gkM7BmSuagifXmbkmJHxH3t9MiGCg6AIRtpbxixZ7qaaPGB+VE Bv5xC0ebznNT1S3vl2c= X-Received: by 10.36.37.130 with SMTP id g124mr432320itg.114.1502934915567; Wed, 16 Aug 2017 18:55:15 -0700 (PDT) Received: from moondust.localdomain.nodomain.none ([184.151.179.113]) by smtp.gmail.com with ESMTPSA id 193sm989096ioo.84.2017.08.16.18.55.14 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Wed, 16 Aug 2017 18:55:15 -0700 (PDT) From: nljlistbox2@gmail.com (N. Jackson) To: Drew Adams Subject: Re: bug#25428: 25.1; Incorrect doc string for `delete-selection-mode' References: Date: Wed, 16 Aug 2017 21:55:09 -0400 In-Reply-To: (Drew Adams's message of "Thu, 12 Jan 2017 08:24:39 -0800 (PST)") Message-ID: <87efsbrm9u.fsf@moondust.localdomain> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: 0.7 (/) X-Debbugs-Envelope-To: 25428 Cc: 25428@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.7 (/) At 07:24 -0800 on Thursday 2017-01-12, Drew Adams wrote: > The doc string says this: > > If called from Lisp, enable the mode if ARG is omitted or nil. > > That is completely wrong. This is an ordinary minor mode, > defined using `define-minor-mode', whose doc string says this: > > When called from Lisp, the mode command toggles the mode if > the argument is =E2=80=98toggle=E2=80=99, disables the mode if the argu= ment is > a non-positive integer, and enables the mode otherwise > (including if the argument is omitted or nil or a positive > integer). Hi Drew, I do not see any contradiction between these two statements. Maybe one of us is misreading them? In particular, I find that the behaviour of `delete-selection-mode' (the function) when called from Lisp matches both statements in every particular, so I don't see what you mean by "completely wrong". > E.g., `(delete-selection-mode t)' ENABLES the mode, even though the > `delete-selection-mode' doc string says that it DISABLES it. Yes, this enables the mode, but no, the doc string does *not* say this disables it. (In fact, it is silent on how to disable it from Lisp.) Am I missing something? Admittedly, the part of its doc string that says how to use the `delete-selection-mode' function from Lisp seems inadequate: It doesn't say how to toggle the mode, it doesn't say how to disable the mode, and the methods it mentions for enabling the mode do not include the most straightforward one (passing it `t'). [Temporary minor rant: Personally it seems absurd to me that a `nil' argument doesn't turn a minor mode off; and that calling the minor mode function with no argument doesn't toggle it. But that is all history of course.] Anyway, does it make sense to re-document the canonical behaviour of minor mode commands in the doc string of every minor mode command? Maybe it would be better (as I think you might have suggested in another bug report back in January) if the doc string of the each minor mode command had a link to the documentation of the canonical behaviour. N. From debbugs-submit-bounces@debbugs.gnu.org Wed Aug 16 22:22:46 2017 Received: (at 25428) by debbugs.gnu.org; 17 Aug 2017 02:22:46 +0000 Received: from localhost ([127.0.0.1]:41769 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1diASM-0003KI-9N for submit@debbugs.gnu.org; Wed, 16 Aug 2017 22:22:46 -0400 Received: from mail-io0-f193.google.com ([209.85.223.193]:37817) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1diASK-0003K1-Nu for 25428@debbugs.gnu.org; Wed, 16 Aug 2017 22:22:44 -0400 Received: by mail-io0-f193.google.com with SMTP id c74so3317923iod.4 for <25428@debbugs.gnu.org>; Wed, 16 Aug 2017 19:22:44 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=jqRubkmg/cdGyvmYDi78q84v3Kt4qrfp3xoIuVUhlGw=; b=ChX5jlVsz0rxhJRs1hpJcVIQ5Z95IjbIxKNYDdFq89XtnFcJI/0iy4rqx06lZYk/bG u2VpuFDyqjS6xkhXpWwCq2sC/6s4ANV5RhA/bOV03jSFY+jh19nIhq6y3qnOYXek7kae v2uMsnXSC8zqiJf7cj38IgEh1+UtJahYs+eDiodxx+Wbvm8/VOBWTZ5KSdyxmNlNwPpP 9IVBW8UOemZ7ev9llbPJU4yos7srFWpZ9nAGEm0O5dTVf8zZlnp4WsRBU5bdQs9slxX3 CClguPZtkJVoVnj9dGJxta1CV1AhJGnDTjVfWy00IpZYWu/vUVPzStT+1EOZpj6BFv0G 8oXA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:references:date :in-reply-to:message-id:user-agent:mime-version; bh=jqRubkmg/cdGyvmYDi78q84v3Kt4qrfp3xoIuVUhlGw=; b=CYkx+NZ0w4K1VETvHSEaDvNi0FrFy5hYQGSf3jSgtDJJXpCU3/H+nt6zP0cx6lxNS1 +jTdEeXDM7+SnbH+avxju6VjKPLfYNsmBxlzRDE4ufJihKYp0FAC0pBVdPxejq/wL0hh jeMtjiBjEuLLkO1lT3HNZwJ6AoBRdcdiJNlrbr8sPjnYiVEfY4x3WxPnWQb02IM/9jsg 3wyHXUrlIEv2noGKgZI54q+yWTJicWwS+IosPjx9vjfTF8Y/zL2iDQU98o2n5pcJBHIp +3hFN1SZHd+dzzsABXAoa8PezcrvfQyOG3vPG9C2/gUC9kZUq6xHYQPaVlngpTzDbQmP FGhA== X-Gm-Message-State: AHYfb5h/7ZX4VMY2rZrWXCckOQTlF8RW/ND4r0QQSGXDjCq7pD9wvJB7 sb59hsxBjKyIx8Ea X-Received: by 10.107.132.233 with SMTP id o102mr3788902ioi.214.1502936559062; Wed, 16 Aug 2017 19:22:39 -0700 (PDT) Received: from zony ([45.2.119.49]) by smtp.googlemail.com with ESMTPSA id m44sm249430iti.0.2017.08.16.19.22.37 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Wed, 16 Aug 2017 19:22:37 -0700 (PDT) From: npostavs@users.sourceforge.net To: nljlistbox2@gmail.com (N. Jackson) Subject: Re: bug#25428: 25.1; Incorrect doc string for `delete-selection-mode' References: <87efsbrm9u.fsf@moondust.localdomain> Date: Wed, 16 Aug 2017 22:24:15 -0400 In-Reply-To: <87efsbrm9u.fsf@moondust.localdomain> (N. Jackson's message of "Wed, 16 Aug 2017 21:55:09 -0400") Message-ID: <874lt7ylrk.fsf@users.sourceforge.net> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.2.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Score: -2.1 (--) X-Debbugs-Envelope-To: 25428 Cc: 25428@debbugs.gnu.org, Drew Adams X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.1 (--) nljlistbox2@gmail.com (N. Jackson) writes: > [Temporary minor rant: Personally it seems absurd to me that a > `nil' argument doesn't turn a minor mode off; and that calling the > minor mode function with no argument doesn't toggle it. But that > is all history of course.] There is a good reason to have it like that: it allows doing (add-hook 'some-hook #'the-minor-mode) Rather than having to do (add-hook 'some-hook (lambda () (the-minor-mode +1))) or (defun turn-on-the-minor-mode () (the-minor-mode +1)) (add-hook 'some-hook #'turn-on-the-minor-mode) From debbugs-submit-bounces@debbugs.gnu.org Wed Aug 16 23:26:13 2017 Received: (at 25428) by debbugs.gnu.org; 17 Aug 2017 03:26:13 +0000 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 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 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 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 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 MIME-Version: 1.0 Message-ID: <2e0430c1-4783-4b53-ac95-300282a1a6be@default> Date: Wed, 16 Aug 2017 20:25:31 -0700 (PDT) From: Drew Adams To: nljlistbox2@gmail.com Subject: RE: bug#25428: 25.1; Incorrect doc string for `delete-selection-mode' References: <87efsbrm9u.fsf@moondust.localdomain> 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)] Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Source-IP: userv0021.oracle.com [156.151.31.71] X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: 25428 Cc: 25428@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.3 (--) 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. From debbugs-submit-bounces@debbugs.gnu.org Sat Aug 26 05:03:40 2017 Received: (at 25428-done) by debbugs.gnu.org; 26 Aug 2017 09:03:40 +0000 Received: from localhost ([127.0.0.1]:55938 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dlX0G-0000Sl-Ee for submit@debbugs.gnu.org; Sat, 26 Aug 2017 05:03:40 -0400 Received: from eggs.gnu.org ([208.118.235.92]:32955) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1dlX0E-0000SY-L0 for 25428-done@debbugs.gnu.org; Sat, 26 Aug 2017 05:03:39 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dlX06-0001Qn-R4 for 25428-done@debbugs.gnu.org; Sat, 26 Aug 2017 05:03:33 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,RP_MATCHES_RCVD autolearn=disabled version=3.3.2 Received: from fencepost.gnu.org ([2001:4830:134:3::e]:59437) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dlX06-0001Qh-NV; Sat, 26 Aug 2017 05:03:30 -0400 Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:4484 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1dlX05-0005XD-NB; Sat, 26 Aug 2017 05:03:30 -0400 Date: Sat, 26 Aug 2017 12:03:20 +0300 Message-Id: <83tw0u66qv.fsf@gnu.org> From: Eli Zaretskii To: Drew Adams In-reply-to: <2e0430c1-4783-4b53-ac95-300282a1a6be@default> (message from Drew Adams on Wed, 16 Aug 2017 20:25:31 -0700 (PDT)) Subject: Re: bug#25428: 25.1; Incorrect doc string for `delete-selection-mode' References: <87efsbrm9u.fsf@moondust.localdomain> <2e0430c1-4783-4b53-ac95-300282a1a6be@default> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-Spam-Score: -5.0 (-----) X-Debbugs-Envelope-To: 25428-done Cc: 25428-done@debbugs.gnu.org, nljlistbox2@gmail.com X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Eli Zaretskii Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) > Date: Wed, 16 Aug 2017 20:25:31 -0700 (PDT) > From: Drew Adams > Cc: 25428@debbugs.gnu.org > > 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 Thanks, I fixed the doc string to include the missing information. From unknown Sat Jun 14 19:26:20 2025 Received: (at fakecontrol) by fakecontrolmessage; To: internal_control@debbugs.gnu.org From: Debbugs Internal Request Subject: Internal Control Message-Id: bug archived. Date: Sat, 23 Sep 2017 11:24:04 +0000 User-Agent: Fakemail v42.6.9 # This is a fake control message. # # The action: # bug archived. thanks # This fakemail brought to you by your local debbugs # administrator