GNU bug report logs - #6335
24.0.50; doc for define-minor-mode: specify ARG

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 6335 in the body.
You can then email your comments to 6335 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.50; doc for define-minor-mode: specify ARG
Date: Wed, 2 Jun 2010 15:07:28 -0700

(elisp) Minor Mode Conventions says this about a minor-mode command:
 
 The command should accept one optional argument.  If the argument
 is `nil', it should toggle the mode (turn it on if it is off, and
 off if it is on).  It should turn the mode on if the argument is a
 positive integer, the symbol `t', or a list whose CAR is one of
 those.  It should turn the mode off if the argument is a negative
 integer or zero, the symbol `-', or a list whose CAR is a negative
 integer or zero.  The meaning of other arguments is not specified.
 
`define-minor-mode' defines such a command.  But the doc for
`define-minor-mode' does not let you know the identity of the parameter
(which is ARG) or anything about where its value comes from
interactively.  It should, for at least these reasons:
 
1. A programmer can use the value.  It is one thing to know that a
positive arg turns the mode on.  It is another thing to know what the
arg name is, so that the command body can recuperate that value and use
it.  For example, the body of the command could do something different,
depending on the value:
 
(cond ((integer arg) (if (> arg 0) do-foo do-fa))
      ((consp arg) ...)
      (arg ...)
      (t ...))
 
2. This would require Emacs developers to maintain `define-minor-mode'
so that the name ARG is respected.  Yes, that's a good thing, not a bad
thing.  The argument should explicitly be part of the spec defining
`define-minor-mode'.  Programmers will anyway use `symbol-function' to
find out what the parameter is, and it is better that Emacs Dev
recognize this, respect the parameter name, and document it.
 
The doc should also state clearly that the _raw prefix argument_ is used
as ARG interactively.  Programmers can then take advantage of that fact
also.  Knowing this, they can easily define a minor-mode command that
lets users pass a significant value via a prefix arg.
 
All of this is important, missing info for programmers.
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2010-05-23 on G41R2F1
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/xpm/include'
 

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: "Drew Adams" <drew.adams <at> oracle.com>
Subject: Re: bug#6335: 24.0.50; doc for define-minor-mode: specify ARG
Date: Wed, 02 Jun 2010 21:54:43 -0400

> (cond ((integer arg) (if (> arg 0) do-foo do-fa))
>       ((consp arg) ...)
>       (arg ...)
>       (t ...))

I do not want to support this.
 
> The doc should also state clearly that the _raw prefix argument_ is used
> as ARG interactively.

It's not the case.

> Programmers can then take advantage of that fact also.  Knowing this,
> they can easily define a minor-mode command that lets users pass
> a significant value via a prefix arg.
 
And I don't want to support this either.

If people want to write functions that behave somewhat like minor modes
but with slightly different calling conventions, they can do that just
fine with `defun'.


        Stefan

Previous Next

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