GNU bug report logs - #10909
24.0.94; doc of `define-minor-mode'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 10909 in the body.
You can then email your comments to 10909 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.94; doc of `define-minor-mode'
Date: Tue, 28 Feb 2012 18:54:47 -0800

The doc says that the mode function that gets defined accepts an
optional argument.  The interactive description is OK.
 
The non-interactive description says only "When called from Lisp, it
enables the mode if the argument is omitted or nil, and toggles the mode
if the argument is `toggle'."
 
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.
 
The doc should, at a minimum, say what kinds of non-nil arguments it
expects (e.g. integer).
 
Personally, I think it should probably go beyond that and say also what
it does with other non-nil args, but that's your call.
 

In GNU Emacs 24.0.94.1 (i386-mingw-nt5.1.2600)
 of 2012-02-26 on MARVIN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --no-opt --enable-checking --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include'
 

Message #10 received at 10909-done <at> debbugs.gnu.org (full text, mbox):

From: Chong Yidong <cyd <at> gnu.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 10909-done <at> debbugs.gnu.org
Subject: Re: bug#10909: 24.0.94; doc of `define-minor-mode'
Date: Sat, 22 Sep 2012 23:25:59 +0800

"Drew Adams" <drew.adams <at> oracle.com> writes:

> The non-interactive description says only "When called from Lisp, it
> enables the mode if the argument is omitted or nil, and toggles the mode
> if the argument is `toggle'."
>  
> 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.

Message #13 received at 10909 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: 10909 <at> debbugs.gnu.org
Cc: cyd <at> gnu.org
Subject: Re: bug#10909: 24.0.94; doc of `define-minor-mode'
Date: Sun, 23 Sep 2012 11:25:03 -0400

>> 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.


        Stefan

Message #16 received at 10909 <at> debbugs.gnu.org (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Stefan Monnier'" <monnier <at> iro.umontreal.ca>, <10909 <at> debbugs.gnu.org>
Cc: cyd <at> gnu.org
Subject: RE: bug#10909: 24.0.94; doc of `define-minor-mode'
Date: Sun, 23 Sep 2012 11:05:35 -0700

> >> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.