From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode commands Date: Tue, 9 Jun 2020 08:40:12 -0700 (PDT) Message-ID: <4a54194b-effc-41a1-836f-2fb71ad11a5a@default> References: <963d4189-17dc-4f4e-9993-0335fa271e50@default> <83k10kafha.fsf@gnu.org> <9d7f8447-1c0b-46db-a40c-c1ed2a398c46@default> <838sh081lt.fsf@gnu.org>> <87wo4jb33s.fsf@web.de>> <83y2oz6j6x.fsf@gnu.org>> <30c91bcf-044c-4d93-8ca8-bd407d7bd6b0@default> <87mu5dbhqv.fsf@web.de> <9a2f8463-42a6-4f0c-82d9-de15192fffe2@default> <87h7vkbrh3.fsf@web.de> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="102938"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 41727@debbugs.gnu.org To: Michael Heerdegen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Tue Jun 09 17:41:26 2020 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 1jigNR-000QhH-GQ for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 09 Jun 2020 17:41:25 +0200 Original-Received: from localhost ([::1]:48384 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jigNQ-0003iL-E8 for geb-bug-gnu-emacs@m.gmane-mx.org; Tue, 09 Jun 2020 11:41:24 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:38336) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jigN6-0003UQ-HE for bug-gnu-emacs@gnu.org; Tue, 09 Jun 2020 11:41:04 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:49070) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jigN5-0007c4-45 for bug-gnu-emacs@gnu.org; Tue, 09 Jun 2020 11:41:04 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1jigN5-0004Be-1G for bug-gnu-emacs@gnu.org; Tue, 09 Jun 2020 11:41:03 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 09 Jun 2020 15:41:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 41727 X-GNU-PR-Package: emacs Original-Received: via spool by 41727-submit@debbugs.gnu.org id=B41727.159171722516021 (code B ref 41727); Tue, 09 Jun 2020 15:41:02 +0000 Original-Received: (at 41727) by debbugs.gnu.org; 9 Jun 2020 15:40:25 +0000 Original-Received: from localhost ([127.0.0.1]:60612 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jigMS-0004AL-RQ for submit@debbugs.gnu.org; Tue, 09 Jun 2020 11:40:25 -0400 Original-Received: from userp2130.oracle.com ([156.151.31.86]:45064) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1jigMR-0004A6-W5 for 41727@debbugs.gnu.org; Tue, 09 Jun 2020 11:40:24 -0400 Original-Received: from pps.filterd (userp2130.oracle.com [127.0.0.1]) by userp2130.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 059FcSIS064190; Tue, 9 Jun 2020 15:40:18 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2020-01-29; bh=f1cmXUmxdrdeDl8V6uYGG162XG8t1rWorF3KST0SZDo=; b=XC/qNRF4Y6muH00ZQwbtL79F3KfJd1pHcKI+ot5gktYsa3deRXTMq7LW4gq9/eWfAcOJ Sw9sLynjhDbQlwN1ZBlPFxTNaNqWIIf6WPXNgO/DlRR1311hPy0iYfSPYjSlLF7pMwqk MwMMiI92hoY/+jZqkNp7Zc74+OomSOkARW3Nt7CDtQLFI3d1dA1JQ/z4pwDFhnKCD+6Y 7ewoYdzgqk7BGGIWpp+VtUc2eSu3qfT382AA2S+yTkpvRzfbSYSlGlhkrU2CTPZSGdL5 B4ulSt2n5vqVEJMC4/uYBgs+CM4wf8s2LPpyucbeHrBRxggh+0LGwOOj7rZmtQ74EaH4 7w== Original-Received: from aserp3020.oracle.com (aserp3020.oracle.com [141.146.126.70]) by userp2130.oracle.com with ESMTP id 31g2jr5j17-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=FAIL); Tue, 09 Jun 2020 15:40:18 +0000 Original-Received: from pps.filterd (aserp3020.oracle.com [127.0.0.1]) by aserp3020.oracle.com (8.16.0.42/8.16.0.42) with SMTP id 059FcbKm030331; Tue, 9 Jun 2020 15:40:17 GMT Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserp3020.oracle.com with ESMTP id 31gn265f7n-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 09 Jun 2020 15:40:16 +0000 Original-Received: from abhmp0019.oracle.com (abhmp0019.oracle.com [141.146.116.25]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id 059FeEE3016786; Tue, 9 Jun 2020 15:40:14 GMT In-Reply-To: <87h7vkbrh3.fsf@web.de> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.5005.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9647 signatures=668680 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 spamscore=0 suspectscore=0 mlxscore=0 phishscore=0 adultscore=0 bulkscore=0 malwarescore=0 mlxlogscore=999 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2004280000 definitions=main-2006090118 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9647 signatures=668680 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 adultscore=0 impostorscore=0 cotscore=-2147483648 priorityscore=1501 spamscore=0 suspectscore=0 lowpriorityscore=0 bulkscore=0 mlxlogscore=999 malwarescore=0 mlxscore=0 phishscore=0 clxscore=1015 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2004280000 definitions=main-2006090118 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:181790 Archived-At: > > > How about leaving only cases like ARG -> '- undocumented? > > > > > > 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 if the argument is a > > > positive integer or omitted or nil. > > > > That's what we say now, and the reason I filed the bug. >=20 > No, it's not, it doesn't contradict the implementation. Did you read > carefully? I think I did. We don't use exactly the same words, but I think we do say just that. When called from Lisp, the mode command toggles the mode if the argument is `toggle',=20 Verbatim the same. disables the mode if the argument is a non-positive integer, Verbatim the same. and enables the mode otherwise (including if the argument is omitted or nil or a positive integer). OK, your text doesn't say "otherwise". Your text is less exact, since the "otherwise" is correct - omitted/nil and positive integer constitute a subset of what's true. Is that really your suggestion, to not document that something other than omitted, nil and a positive integer enables the mode? To me, that would be a step backward, not forward. That doesn't correspond to what the code does. > > Consider a case where some command A invokes a minor-mode > > command B, to turn B on or off for some purpose/extent. > > Consider the case where A's prefix arg is passed to B, to > > do that. > > > > The programmer writing the Lisp code to define A should > > know that s?he can just pass the raw prefix arg. The > > resulting code will be simpler, easier to read, etc. >=20 > We don't know if the original author intended the semantics of the > documentation or of the implementation. If we are sure the current > implementation is what was intended I would be ok with documenting it, > but it's really far from important IMHO. Until the code is changed, e.g. because someone thinks the behavior is wrong, the doc should reflect it. I, for one, think the behavior is OK as is. The use case I just gave (cited above) is one argument for it. Many commands have the `interactive' form massage the prefix arg, to present something a bit different to the body. E.g., a change from raw to numeric prefix value is done in the `interactive' form, for whatever reason. This command doesn't work that way. Instead, what is passed to Lisp is the raw prefix arg, and it is the body (which also corresponds to a non-interactive call) that converts that to a numeric value. Someone (and `d-m-mode' has been worked over more than once wrt its interactive-vs-Lisp behavior, I believe) presumably deliberately decided that this command should act differently. Many commands (most, I think) make it so that the body gets just what it needs, and any compensation for interactivity is taken care of only in the `interactive' spec. Someone presumably thought this command should be an exception in that regard. Until someone decides otherwise, and changes the behavior (which I doubt will happen, in particular because of backward incompatibility), IMO it's the doc that needs to be changed to fit the behavior, not the other way around. I don't understand the hesitation to make the doc say just what the truth is. It doesn't take any more text. I already suggested wording, and I made clear that other wording that says the same thing (describes the behavior accurately) would be fine instead. What's the pushback, here? Why shouldn't we make the doc tell the real story wrt the ARG that Lisp expects?