From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Phil Sainty Newsgroups: gmane.emacs.bugs Subject: bug#49843: 28.0.50; Error in docstring after using define-globalized-minor-mode Date: Tue, 03 Aug 2021 21:18:18 +1200 Message-ID: References: <70a6133fb48569d5bcc1a1bf191ce582@webmail.orcon.net.nz> Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="2924"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Orcon Webmail Cc: 49843@debbugs.gnu.org To: dalanicolai@gmail.com Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Aug 03 11:36:54 2021 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1mAqr0-0000ZB-5U for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 03 Aug 2021 11:36:54 +0200 Original-Received: from localhost ([::1]:40094 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mAqqy-0006zk-Vj for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 03 Aug 2021 05:36:52 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:58264) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mAqqc-0006zL-VJ for bug-gnu-emacs@gnu.org; Tue, 03 Aug 2021 05:36:30 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:56541) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mAqqc-0002G4-Ep for bug-gnu-emacs@gnu.org; Tue, 03 Aug 2021 05:36:30 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1mAqZi-0003Dz-Jj for bug-gnu-emacs@gnu.org; Tue, 03 Aug 2021 05:19:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Phil Sainty Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 03 Aug 2021 09:19:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 49843 X-GNU-PR-Package: emacs Original-Received: via spool by 49843-submit@debbugs.gnu.org id=B49843.162798230412306 (code B ref 49843); Tue, 03 Aug 2021 09:19:02 +0000 Original-Received: (at 49843) by debbugs.gnu.org; 3 Aug 2021 09:18:24 +0000 Original-Received: from localhost ([127.0.0.1]:39853 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mAqZ6-0003CQ-2y for submit@debbugs.gnu.org; Tue, 03 Aug 2021 05:18:24 -0400 Original-Received: from smtp-3.orcon.net.nz ([60.234.4.44]:36369) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mAqZ3-0003C9-0S for 49843@debbugs.gnu.org; Tue, 03 Aug 2021 05:18:22 -0400 Original-Received: from [10.253.37.70] (port=49994 helo=webmail.orcon.net.nz) by smtp-3.orcon.net.nz with esmtpa (Exim 4.90_1) (envelope-from ) id 1mAqZ0-0002dR-FQ; Tue, 03 Aug 2021 21:18:19 +1200 Original-Received: from ip-116-251-162-85.kinect.net.nz ([116.251.162.85]) via [10.253.37.253] by webmail.orcon.net.nz with HTTP (HTTP/1.1 POST); Tue, 03 Aug 2021 21:18:18 +1200 In-Reply-To: <70a6133fb48569d5bcc1a1bf191ce582@webmail.orcon.net.nz> X-Sender: psainty@orcon.net.nz X-GeoIP: -- X-Spam_score: -2.9 X-Spam_score_int: -28 X-Spam_bar: -- X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list 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-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:211093 Archived-At: In fact I was looking in Emacs 27, and it's all changed in 28, so apologies for my confusion. We actually now have this template: (defconst easy-mmode--arg-docstring " This is a minor mode. If called interactively, toggle the `%s' mode. If the prefix argument is positive, enable the mode, and if it is zero or negative, disable the mode. If called from Lisp, toggle the mode if ARG is `toggle'. Enable the mode if ARG is nil, omitted, or is a positive number. Disable the mode if ARG is a negative number. To check whether the minor mode is enabled in the current buffer, evaluate `%S'. The mode's hook is called both when the mode is enabled and when it is disabled.") That description still doesn't specify what happens with other values, and I realise you're saying that the docstring of `define-minor-mode' itself has a different, more comprehensive explanation: "When called from Lisp, the mode command toggles the mode if the argument is `toggle', 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)." https://debbugs.gnu.org/cgi/bugreport.cgi?bug=44341 is related. I notice the commit message for 5cea77af41b59ba6f6386264812c36ec31ba2efc says: * lisp/emacs-lisp/easy-mmode.el (easy-mmode--arg-docstring): Only document the values we want to support, not the ones we actually support. So the failure to say what happens if you pass something other than an integer or 'toggle seems intentional, as other kinds of argument shouldn't ever be used. I expect that globalized modes should also use the text of the `easy-mmode--arg-docstring' template.