From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#10909: 24.0.94; doc of `define-minor-mode' Date: Sun, 23 Sep 2012 11:05:35 -0700 Message-ID: <232BEA225630459F82B1A4FE183AA54C@us.oracle.com> References: <87y5k2dqpk.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1348423591 8521 80.91.229.3 (23 Sep 2012 18:06:31 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 23 Sep 2012 18:06:31 +0000 (UTC) Cc: cyd@gnu.org To: "'Stefan Monnier'" , <10909@debbugs.gnu.org> Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Sep 23 20:06:35 2012 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1TFqZZ-00052z-5C for geb-bug-gnu-emacs@m.gmane.org; Sun, 23 Sep 2012 20:06:29 +0200 Original-Received: from localhost ([::1]:58024 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TFqZU-0003dW-DD for geb-bug-gnu-emacs@m.gmane.org; Sun, 23 Sep 2012 14:06:24 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:39352) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TFqZQ-0003c4-SY for bug-gnu-emacs@gnu.org; Sun, 23 Sep 2012 14:06:23 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1TFqZJ-00053B-RG for bug-gnu-emacs@gnu.org; Sun, 23 Sep 2012 14:06:20 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:41941) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1TFqZJ-00052x-MR for bug-gnu-emacs@gnu.org; Sun, 23 Sep 2012 14:06:13 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1TFqb3-0003R4-W3 for bug-gnu-emacs@gnu.org; Sun, 23 Sep 2012 14:08:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 23 Sep 2012 18:08:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 10909 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 10909-submit@debbugs.gnu.org id=B10909.134842366113179 (code B ref 10909); Sun, 23 Sep 2012 18:08:01 +0000 Original-Received: (at 10909) by debbugs.gnu.org; 23 Sep 2012 18:07:41 +0000 Original-Received: from localhost ([127.0.0.1]:51487 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TFqai-0003QU-Vx for submit@debbugs.gnu.org; Sun, 23 Sep 2012 14:07:41 -0400 Original-Received: from rcsinet15.oracle.com ([148.87.113.117]:18655) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1TFqag-0003QN-Kz for 10909@debbugs.gnu.org; Sun, 23 Sep 2012 14:07:39 -0400 Original-Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by rcsinet15.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with ESMTP id q8NI5lRa014319 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sun, 23 Sep 2012 18:05:48 GMT Original-Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id q8NI5kCE001107 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sun, 23 Sep 2012 18:05:47 GMT Original-Received: from abhmt107.oracle.com (abhmt107.oracle.com [141.146.116.59]) by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id q8NI5k8D012964; Sun, 23 Sep 2012 13:05:46 -0500 Original-Received: from dradamslap1 (/10.159.184.34) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sun, 23 Sep 2012 11:05:46 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 Thread-Index: Ac2Zn6MrNYIm1JXnTiaKGvMQJHgKxAAEg0aw X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 140.186.70.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-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:64825 Archived-At: > >> IOW, it says nothing about what happens when an arg is > >> passed that is not nil or omitted or `toggle'. > >> And I've seen at least one user try to use `(foo-mode t)'. > >> It turns out that that has the same effect as `(foo-mode 1)', > >> but nothing in the doc says that it should. > > > > Fixed in trunk. > > Actually, I think the right fix is to replace calls that use t with > calls that use 1, rather than documenting the accidental behavior. I don't know exactly what the fix was. (The latest build I have is GNU Emacs 24.2.50.1 (i386-mingw-nt5.1.2600) of 2012-09-17 on MARVIN.) But I think perhaps you are missing the point. The doc says nothing about ANY non-nil value other than `toggle'. It thus says NOTHING about how to turn OFF the mode using Lisp. It also does not say that 1 or 42 or t or `stefan' turns the mode on. (In particular, it does not favor 1 or 42 over t.) At the very least the doc should say that a positive arg turns it on and a non-positive value turns it off. That's the point. The doc is OK wrt interactive use, but not wrt Lisp calls. It's not about t vs 1 in any existing Lisp code. It's about saying what the possible argument values do. Presumably, most users calling `define-minor-mode' will mention in the doc of their new mode command how to call it from Lisp, since some users of their mode, especially if it is global, will prefer to turn it on in their init files. That is, presumably most users of `define-minor-mode' will NOT just document their new mode following the example given in the manual: "If enabled, foo on you!". They will hopefully document it in a way that tells users how to turn the mode on and off, both interactively and using Lisp. (That part could be, but is not, done automatically by `define-minor-mode'.) To document that behavior for their users, users of `define-minor-mode' should have access to doc for the macro that tells them how users of their new modes can turn them on and off using Lisp. It's really the least they can expect from a general utility macro.