bug#10909: 24.0.94; doc of `define-minor-mode'

bug#10909: 24.0.94; doc of `define-minor-mode'

[Drew Adams]

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'
 

bug#10909: 24.0.94; doc of `define-minor-mode'

[Chong Yidong]

"Drew Adams" <drew.adams@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.

bug#10909: 24.0.94; doc of `define-minor-mode'

[Stefan Monnier]

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

bug#10909: 24.0.94; doc of `define-minor-mode'

[Drew Adams]

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