GNU bug report logs - #24706
26.0.50; Minor mode functions should do strict argument type checking

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 24706 in the body.
You can then email your comments to 24706 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: Philipp Stephani <p.stephani2 <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.0.50; Minor mode functions should do strict argument type checking
Date: Sun, 16 Oct 2016 17:45:58 +0200

After defining a minor mode with

(define-minor-mode foo-mode nil)

its docstring will be

"Toggle Foo mode on or off.
With a prefix argument ARG, enable Foo mode if ARG is
positive, and disable it otherwise.  If called from Lisp, enable
the mode if ARG is omitted or nil, and toggle it if ARG is ‘toggle’."

This appears to indicate that

(foo-mode 'banana)

should disable foo-mode, but it enables it.  I think minor modes should
simply not allow anything but integers and 'toggle for ARG, avoiding
this confusion.


In GNU Emacs 26.0.50.3 (x86_64-apple-darwin16.0.0, NS appkit-1504.00 Version 10.12 (Build 16A323))
 of 2016-10-16 built on p
Repository revision: cf566b46a6cf85c6d54d0b0db80e32ed6ae8d1ca
Windowing system distributor 'Apple', version 10.3.1504
Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.
Making completion list...

Configured using:
 'configure --with-modules --enable-checking
 --enable-check-lisp-object-type --without-xml2'

Configured features:
RSVG IMAGEMAGICK DBUS NOTIFY ACL GNUTLS ZLIB TOOLKIT_SCROLL_BARS NS
MODULES

Important settings:
  value of $LANG: de_DE.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Lisp Interaction

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message subr-x puny seq byte-opt gv
bytecomp byte-compile cl-extra help-mode cconv cl-loaddefs pcase cl-lib
dired dired-loaddefs format-spec rfc822 mml easymenu mml-sec
password-cache epa derived epg epg-config gnus-util rmail rmail-loaddefs
mm-decode mm-bodies mm-encode mail-parse rfc2231 mailabbrev gmm-utils
mailheader sendmail rfc2047 rfc2045 ietf-drums mm-util mail-prsvr
mail-utils time-date mule-util tooltip eldoc electric uniquify
ediff-hook vc-hooks lisp-float-type mwheel term/ns-win ns-win
ucs-normalize term/common-win tool-bar dnd fontset image regexp-opt
fringe tabulated-list newcomment elisp-mode lisp-mode prog-mode register
page menu-bar rfn-eshadow timer select scroll-bar mouse jit-lock
font-lock syntax facemenu font-core term/tty-colors frame cl-generic
cham georgian utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao
korean japanese eucjp-ms cp51932 hebrew greek romanian slovak czech
european ethiopic indian cyrillic chinese charscript case-table epa-hook
jka-cmpr-hook help simple abbrev obarray minibuffer cl-preloaded nadvice
loaddefs button faces cus-face macroexp files text-properties overlay
sha1 md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote dbusbind kqueue cocoa ns multi-tty
make-network-process emacs)

Memory information:
((conses 16 206734 11456)
 (symbols 48 20333 0)
 (miscs 40 50 157)
 (strings 32 18351 5209)
 (string-bytes 1 593891)
 (vectors 16 35291)
 (vector-slots 8 676180 5448)
 (floats 8 183 64)
 (intervals 56 219 0)
 (buffers 976 12))

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Philipp Stephani <p.stephani2 <at> gmail.com>, 24706 <at> debbugs.gnu.org
Subject: RE: bug#24706: 26.0.50; Minor mode functions should do strict
 argument type checking
Date: Sun, 16 Oct 2016 09:12:14 -0700 (PDT)

> (define-minor-mode foo-mode nil)
> its docstring will be
> 
> "Toggle Foo mode on or off.
> With a prefix argument ARG, enable Foo mode if ARG is
> positive, and disable it otherwise.  If called from Lisp, enable
> the mode if ARG is omitted or nil, and toggle it if ARG is ‘toggle’."
> 
> This appears to indicate that (foo-mode 'banana)
> should disable foo-mode, but it enables it.

No, it does not suggest that.  But to be clearer, it should
probably explicitly address the non-nil and non-`toggle' case,
like so:

  If called from Lisp, enable the mode if ARG is omitted or
  nil, toggle it if ARG is ‘toggle’, and disable it if ARG is
  any other non-nil value.

(And place the Lisp description in a separate paragraph
from the interactive description.)

> I think minor modes should simply not allow anything but
> integers and 'toggle for ARG, avoiding this confusion.

Why?  There is no confusion possible, once the doc string 
explicitly speaks about all possible argument values.

Why would you change the behavior, instead of just clarifying
the doc?

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

From: Noam Postavsky <npostavs <at> users.sourceforge.net>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 24706 <at> debbugs.gnu.org, Philipp Stephani <p.stephani2 <at> gmail.com>
Subject: Re: bug#24706: 26.0.50; Minor mode functions should do strict
 argument type checking
Date: Sun, 16 Oct 2016 12:31:51 -0400

On Sun, Oct 16, 2016 at 12:12 PM, Drew Adams <drew.adams <at> oracle.com> wrote:
>> (define-minor-mode foo-mode nil)
>> its docstring will be
>>
>> "Toggle Foo mode on or off.
>> With a prefix argument ARG, enable Foo mode if ARG is
>> positive, and disable it otherwise.  If called from Lisp, enable
>> the mode if ARG is omitted or nil, and toggle it if ARG is ‘toggle’."
>>
>> This appears to indicate that (foo-mode 'banana)
>> should disable foo-mode, but it enables it.
>
> No, it does not suggest that.  But to be clearer, it should
> probably explicitly address the non-nil and non-`toggle' case,
> like so:
>
>   If called from Lisp, enable the mode if ARG is omitted or
>   nil, toggle it if ARG is ‘toggle’, and disable it if ARG is
>   any other non-nil value.

If the Lisp description is meant to be exhaustive by itself, we should
cover the numeric case too:

   If called from Lisp, enable the mode if ARG is omitted, nil, or a
   positive number; toggle it if ARG is `toggle'; and disable it
   otherwise.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Noam Postavsky <npostavs <at> users.sourceforge.net>
Cc: 24706 <at> debbugs.gnu.org, Philipp Stephani <p.stephani2 <at> gmail.com>
Subject: RE: bug#24706: 26.0.50; Minor mode functions should do strict
 argument type checking
Date: Sun, 16 Oct 2016 09:49:32 -0700 (PDT)

> >> (define-minor-mode foo-mode nil)
> >> its docstring will be
> >>
> >> "Toggle Foo mode on or off.
> >> With a prefix argument ARG, enable Foo mode if ARG is
> >> positive, and disable it otherwise.  If called from Lisp, enable
> >> the mode if ARG is omitted or nil, and toggle it if ARG is ‘toggle’."
> >>
> >> This appears to indicate that (foo-mode 'banana)
> >> should disable foo-mode, but it enables it.
> >
> > No, it does not suggest that.  But to be clearer, it should
> > probably explicitly address the non-nil and non-`toggle' case,
> > like so:
> >
> >   If called from Lisp, enable the mode if ARG is omitted or
> >   nil, toggle it if ARG is ‘toggle’, and disable it if ARG is
> >   any other non-nil value.
> 
> If the Lisp description is meant to be exhaustive by itself, we should
> cover the numeric case too:
> 
>    If called from Lisp, enable the mode if ARG is omitted, nil, or a
>    positive number; toggle it if ARG is `toggle'; and disable it
>    otherwise.

Yes, and anyway what I wrote was wrong.

The doc string of `define-minor-mode' has it right, as does your
suggestion:

  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 otherwise (including
  if the argument is omitted or nil or a positive integer).

I'd suggest the same order as in the `define-minor-mode' doc:

  When called from Lisp:
  * Toggle the mode if ARG is `toggle'.
  * Disable it if ARG is a non-positive integer.
  * Enable it if ARG is anything else.
  

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Noam Postavsky <npostavs <at> users.sourceforge.net>
Cc: 24706 <at> debbugs.gnu.org, p.stephani2 <at> gmail.com, drew.adams <at> oracle.com
Subject: Re: bug#24706: 26.0.50;
 Minor mode functions should do strict argument type checking
Date: Sun, 16 Oct 2016 21:01:14 +0300

> From: Noam Postavsky <npostavs <at> users.sourceforge.net>
> Date: Sun, 16 Oct 2016 12:31:51 -0400
> Cc: 24706 <at> debbugs.gnu.org, Philipp Stephani <p.stephani2 <at> gmail.com>
> 
> > No, it does not suggest that.  But to be clearer, it should
> > probably explicitly address the non-nil and non-`toggle' case,
> > like so:
> >
> >   If called from Lisp, enable the mode if ARG is omitted or
> >   nil, toggle it if ARG is ‘toggle’, and disable it if ARG is
> >   any other non-nil value.
> 
> If the Lisp description is meant to be exhaustive by itself, we should
> cover the numeric case too:
> 
>    If called from Lisp, enable the mode if ARG is omitted, nil, or a
>    positive number; toggle it if ARG is `toggle'; and disable it
>    otherwise.

There's a magic word 'also", which should allow us to avoid
repetitions.

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

From: Philipp Stephani <p.stephani2 <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>, 24706 <at> debbugs.gnu.org
Subject: Re: bug#24706: 26.0.50; Minor mode functions should do strict
 argument type checking
Date: Sun, 16 Oct 2016 18:13:01 +0000

[Message part 1 (text/plain, inline)]

Drew Adams <drew.adams <at> oracle.com> schrieb am So., 16. Okt. 2016 um
18:12 Uhr:

> > (define-minor-mode foo-mode nil)
> > its docstring will be
> >
> > "Toggle Foo mode on or off.
> > With a prefix argument ARG, enable Foo mode if ARG is
> > positive, and disable it otherwise.  If called from Lisp, enable
> > the mode if ARG is omitted or nil, and toggle it if ARG is ‘toggle’."
> >
> > This appears to indicate that (foo-mode 'banana)
> > should disable foo-mode, but it enables it.
>
> No, it does not suggest that.  But to be clearer, it should
> probably explicitly address the non-nil and non-`toggle' case,
> like so:
>
>   If called from Lisp, enable the mode if ARG is omitted or
>   nil, toggle it if ARG is ‘toggle’, and disable it if ARG is
>   any other non-nil value.
>
> (And place the Lisp description in a separate paragraph
> from the interactive description.)
>
> > I think minor modes should simply not allow anything but
> > integers and 'toggle for ARG, avoiding this confusion.
>
> Why?  There is no confusion possible, once the doc string
> explicitly speaks about all possible argument values.
>
> Why would you change the behavior, instead of just clarifying
> the doc?
>

I generally prefer the behavior to be as strict as possible. Consider
(foo-mode 'disable)
If you read such code, do you assume that this enables foo-mode?
However, in this case I guess it's too late, and fixing the documentation
is indeed more appropriate. BTW, the Elisp manual has the same issue:

     The mode command should accept one optional argument.  If called
     interactively with no prefix argument, it should toggle the mode
     (i.e., enable if it is disabled, and disable if it is enabled).  If
     called interactively with a prefix argument, it should enable the
     mode if the argument is positive and disable it otherwise.

     If the mode command is called from Lisp (i.e., non-interactively),
     it should enable the mode if the argument is omitted or ‘nil’; it
     should toggle the mode if the argument is the symbol ‘toggle’;
     otherwise it should treat the argument in the same way as for an
     interactive call with a numeric prefix argument, as described
     above.

Probably this should be reworded so that the Lisp case doesn't refer to the
interactive case at all. Making the documentation obvious is more important
than avoiding repetition.

[Message part 2 (text/html, inline)]

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

From: Philipp Stephani <p.stephani2 <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>, 24706 <at> debbugs.gnu.org
Subject: Re: bug#24706: 26.0.50; Minor mode functions should do strict
 argument type checking
Date: Sun, 16 Oct 2016 18:25:08 +0000

[Message part 1 (text/plain, inline)]

Philipp Stephani <p.stephani2 <at> gmail.com> schrieb am So., 16. Okt. 2016 um
20:13 Uhr:

> Drew Adams <drew.adams <at> oracle.com> schrieb am So., 16. Okt. 2016 um
> 18:12 Uhr:
>
> > (define-minor-mode foo-mode nil)
> > its docstring will be
> >
> > "Toggle Foo mode on or off.
> > With a prefix argument ARG, enable Foo mode if ARG is
> > positive, and disable it otherwise.  If called from Lisp, enable
> > the mode if ARG is omitted or nil, and toggle it if ARG is ‘toggle’."
> >
> > This appears to indicate that (foo-mode 'banana)
> > should disable foo-mode, but it enables it.
>
> No, it does not suggest that.  But to be clearer, it should
> probably explicitly address the non-nil and non-`toggle' case,
> like so:
>
>   If called from Lisp, enable the mode if ARG is omitted or
>   nil, toggle it if ARG is ‘toggle’, and disable it if ARG is
>   any other non-nil value.
>
> (And place the Lisp description in a separate paragraph
> from the interactive description.)
>
> > I think minor modes should simply not allow anything but
> > integers and 'toggle for ARG, avoiding this confusion.
>
> Why?  There is no confusion possible, once the doc string
> explicitly speaks about all possible argument values.
>
> Why would you change the behavior, instead of just clarifying
> the doc?
>
>
> I generally prefer the behavior to be as strict as possible. Consider
> (foo-mode 'disable)
> If you read such code, do you assume that this enables foo-mode?
> However, in this case I guess it's too late, and fixing the documentation
> is indeed more appropriate. BTW, the Elisp manual has the same issue:
>
>      The mode command should accept one optional argument.  If called
>      interactively with no prefix argument, it should toggle the mode
>      (i.e., enable if it is disabled, and disable if it is enabled).  If
>      called interactively with a prefix argument, it should enable the
>      mode if the argument is positive and disable it otherwise.
>
>      If the mode command is called from Lisp (i.e., non-interactively),
>      it should enable the mode if the argument is omitted or ‘nil’; it
>      should toggle the mode if the argument is the symbol ‘toggle’;
>      otherwise it should treat the argument in the same way as for an
>      interactive call with a numeric prefix argument, as described
>      above.
>
> Probably this should be reworded so that the Lisp case doesn't refer to
> the interactive case at all. Making the documentation obvious is more
> important than avoiding repetition.
>

Attached a patch that uses the wording from `define-minor-mode'.

[Message part 2 (text/html, inline)]

[0001-Clarify-the-behavior-of-minor-mode-commands.txt (text/plain, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Philipp Stephani <p.stephani2 <at> gmail.com>
Cc: 24706 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#24706: 26.0.50;
 Minor mode functions should do strict argument type checking
Date: Sun, 16 Oct 2016 21:51:08 +0300

> From: Philipp Stephani <p.stephani2 <at> gmail.com>
> Date: Sun, 16 Oct 2016 18:25:08 +0000
> 
> Attached a patch that uses the wording from `define-minor-mode'. 

The patch for the ELisp manual simply rearranges the same words, so
it's not clear to me why we would prefer it to what's already there.

As for the doc string, please avoid repetition, it's confusing.  I
suggested to describe the additional features when the mode is called
from Lisp by using the word "also".

Thanks.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Philipp Stephani <p.stephani2 <at> gmail.com>
Cc: 24706 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#24706: 26.0.50;
 Minor mode functions should do strict argument type checking
Date: Sun, 16 Oct 2016 21:53:56 +0300

> From: Philipp Stephani <p.stephani2 <at> gmail.com>
> Date: Sun, 16 Oct 2016 18:13:01 +0000
> 
>  Why would you change the behavior, instead of just clarifying
>  the doc?
> 
> I generally prefer the behavior to be as strict as possible.

Let's not consider changing long-established behavior for purely
theoretical or philosophical reasons.

> Consider
> (foo-mode 'disable)
> If you read such code, do you assume that this enables foo-mode?

It would be a silly thing to do, so it would be worth a bug report.
However, I don't really believe someone in their right minds would do
something like that.

> However, in this case I guess it's too late, and fixing the documentation is indeed more appropriate.

Exactly.

> Probably this should be reworded so that the Lisp case doesn't refer to the interactive case at all. Making the
> documentation obvious is more important than avoiding repetition.

Sorry, I disagree. with the last sentence.  Repetition is a source for
confusion.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Philipp Stephani <p.stephani2 <at> gmail.com>, 24706 <at> debbugs.gnu.org
Subject: RE: bug#24706: 26.0.50; Minor mode functions should do strict
 argument type checking
Date: Sun, 16 Oct 2016 12:50:06 -0700 (PDT)

>> Why would you change the behavior, instead of just clarifying
>> the doc?
>
> I generally prefer the behavior to be as strict as possible.
> Consider (foo-mode 'disable)  If you read such code, do you
> assume that this enables foo-mode?

If I understand the function, then yes.  But I agree that the
doc could make the function behavior clearer.

That example is akin to this:

(deconst two 42)
(+ 3 two)

There are plenty of ways to write code that is perverse in
terms of readability (whether or not it has the right behavior).

> However, in this case I guess it's too late, and fixing the
> documentation is indeed more appropriate.

It would be a backward-incompatible change.  (And I do not
see any advantage to it.  But others might disagree with
me and agree with you.)

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

From: Philipp Stephani <p.stephani2 <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 24706 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#24706: 26.0.50; Minor mode functions should do strict
 argument type checking
Date: Sun, 23 Apr 2017 17:51:32 +0000

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> schrieb am So., 16. Okt. 2016 um 20:51 Uhr:

> > From: Philipp Stephani <p.stephani2 <at> gmail.com>
> > Date: Sun, 16 Oct 2016 18:25:08 +0000
> >
> > Attached a patch that uses the wording from `define-minor-mode'.
>
> The patch for the ELisp manual simply rearranges the same words, so
> it's not clear to me why we would prefer it to what's already there.
>
> As for the doc string, please avoid repetition, it's confusing.  I
> suggested to describe the additional features when the mode is called
> from Lisp by using the word "also".
>
>
I don't think there's any repetition or rearranging here. The key
difference is that when called from Lisp with an argument that is neither
nil nor an integer, the mode is also enabled. That isn't possible for
interactive calls because the argument is always a number.
Maybe something like

"With a prefix argument ARG, enable the mode if ARG is positive, and
disable it if ARG is negative or zero. Additionally, when called from Lisp,
toggle the mode if ARG is the symbol `toggle' and interpret ARG as defined
by `prefix-numeric-value' otherwise."

(and then document the behavior of prefix-numeric-value)

[Message part 2 (text/html, inline)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Philipp Stephani <p.stephani2 <at> gmail.com>
Cc: 24706 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#24706: 26.0.50; Minor mode functions should do strict
 argument type checking
Date: Wed, 26 Apr 2017 14:26:25 +0300

> From: Philipp Stephani <p.stephani2 <at> gmail.com>
> Date: Sun, 23 Apr 2017 17:51:32 +0000
> Cc: drew.adams <at> oracle.com, 24706 <at> debbugs.gnu.org
> 
> Eli Zaretskii <eliz <at> gnu.org> schrieb am So., 16. Okt. 2016 um 20:51 Uhr:
> 
>  > From: Philipp Stephani <p.stephani2 <at> gmail.com>
>  > Date: Sun, 16 Oct 2016 18:25:08 +0000
>  >
>  > Attached a patch that uses the wording from `define-minor-mode'.
> 
>  The patch for the ELisp manual simply rearranges the same words, so
>  it's not clear to me why we would prefer it to what's already there.
> 
> I don't think there's any repetition or rearranging here.

Here's the ELisp manual part of your proposed change:

   If the mode command is called from Lisp (i.e., non-interactively), it
  -should enable the mode if the argument is omitted or @code{nil}; it
  -should toggle the mode if the argument is the symbol @code{toggle};
  -otherwise it should treat the argument in the same way as for an
  -interactive call with a numeric prefix argument, as described above.
  +should toggle the mode if the argument is the symbol @code{toggle}; it
  +should disable the mode if the argument is a non-positive integer;
  +otherwise, e.g., if the argument is omitted or nil or a positive
  +integer, it should enable the mode.

Don't you agree that it does little apart of re-shuffling the same
words?

> The key difference is that when called from Lisp with an
> argument that is neither nil nor an integer, the mode is also enabled.

Why would we want to require that?  This subsection describes the
conventions, it doesn't describe the effect of certain popular
implementation of those conventions, because we don't really want to
_require_ modes to behave in any way beyond the described behavior.

> "With a prefix argument ARG, enable the mode if ARG is positive, and disable it if ARG is negative or zero.

This is almost exactly the same as the current:

  With a prefix argument ARG, enable %s if ARG is
  positive, and disable it otherwise.

> Additionally, when called from Lisp, toggle the mode if ARG is the symbol `toggle' and interpret ARG as
> defined by `prefix-numeric-value' otherwise."

And this is exactly what I suggested back then:

>  As for the doc string, please avoid repetition, it's confusing. I
>  suggested to describe the additional features when the mode is called
>  from Lisp by using the word "also".

The wording I had in mind was similar to yours:

  When called from Lisp, also enable the mode if ARG is omitted or
  nil, and toggle it if ARG is `toggle'.

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

From: Philipp Stephani <p.stephani2 <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 24706 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#24706: 26.0.50; Minor mode functions should do strict
 argument type checking
Date: Sat, 1 Aug 2020 22:47:03 +0200

Am Mi., 26. Apr. 2017 um 13:27 Uhr schrieb Eli Zaretskii <eliz <at> gnu.org>:
>
> > From: Philipp Stephani <p.stephani2 <at> gmail.com>
> > Date: Sun, 23 Apr 2017 17:51:32 +0000
> > Cc: drew.adams <at> oracle.com, 24706 <at> debbugs.gnu.org
> >
> > Eli Zaretskii <eliz <at> gnu.org> schrieb am So., 16. Okt. 2016 um 20:51 Uhr:
> >
> >  > From: Philipp Stephani <p.stephani2 <at> gmail.com>
> >  > Date: Sun, 16 Oct 2016 18:25:08 +0000
> >  >
> >  > Attached a patch that uses the wording from `define-minor-mode'.
> >
> >  The patch for the ELisp manual simply rearranges the same words, so
> >  it's not clear to me why we would prefer it to what's already there.
> >
> > I don't think there's any repetition or rearranging here.
>
> Here's the ELisp manual part of your proposed change:
>
>    If the mode command is called from Lisp (i.e., non-interactively), it
>   -should enable the mode if the argument is omitted or @code{nil}; it
>   -should toggle the mode if the argument is the symbol @code{toggle};
>   -otherwise it should treat the argument in the same way as for an
>   -interactive call with a numeric prefix argument, as described above.
>   +should toggle the mode if the argument is the symbol @code{toggle}; it
>   +should disable the mode if the argument is a non-positive integer;
>   +otherwise, e.g., if the argument is omitted or nil or a positive
>   +integer, it should enable the mode.
>
> Don't you agree that it does little apart of re-shuffling the same
> words?

It also describes what happens when the argument is neither nil nor
`toggle' nor an integer. That is currently unspecified, or rather
implicitly specified by the observable (but unspecified) behavior of
`prefix-numeric-value'.

>
> > The key difference is that when called from Lisp with an
> > argument that is neither nil nor an integer, the mode is also enabled.
>
> Why would we want to require that?  This subsection describes the
> conventions, it doesn't describe the effect of certain popular
> implementation of those conventions, because we don't really want to
> _require_ modes to behave in any way beyond the described behavior.

This isn't about the implementation but the interface, i.e. the
observable behavior of minor mode functions.

>
> > "With a prefix argument ARG, enable the mode if ARG is positive, and disable it if ARG is negative or zero.
>
> This is almost exactly the same as the current:
>
>   With a prefix argument ARG, enable %s if ARG is
>   positive, and disable it otherwise.
>
> > Additionally, when called from Lisp, toggle the mode if ARG is the symbol `toggle' and interpret ARG as
> > defined by `prefix-numeric-value' otherwise."
>
> And this is exactly what I suggested back then:
>
> >  As for the doc string, please avoid repetition, it's confusing. I
> >  suggested to describe the additional features when the mode is called
> >  from Lisp by using the word "also".
>
> The wording I had in mind was similar to yours:
>
>   When called from Lisp, also enable the mode if ARG is omitted or
>   nil, and toggle it if ARG is `toggle'.

That again doesn't describe what happens if neither of these cases apply.
(My suggestion from 2017 also wouldn't work here as-is, because the
behavior of `prefix-numeric-value' isn't defined for these cases
either.)

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Philipp Stephani <p.stephani2 <at> gmail.com>
Cc: 24706 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#24706: 26.0.50; Minor mode functions should do strict
 argument type checking
Date: Sun, 02 Aug 2020 19:13:19 +0300

> From: Philipp Stephani <p.stephani2 <at> gmail.com>
> Date: Sat, 1 Aug 2020 22:47:03 +0200
> Cc: Drew Adams <drew.adams <at> oracle.com>, 24706 <at> debbugs.gnu.org
> 
> Am Mi., 26. Apr. 2017 um 13:27 Uhr schrieb Eli Zaretskii <eliz <at> gnu.org>:
> >
> > > From: Philipp Stephani <p.stephani2 <at> gmail.com>
> > > Date: Sun, 23 Apr 2017 17:51:32 +0000
> > > Cc: drew.adams <at> oracle.com, 24706 <at> debbugs.gnu.org
> > >
> > > Eli Zaretskii <eliz <at> gnu.org> schrieb am So., 16. Okt. 2016 um 20:51 Uhr:
> > >
> > >  > From: Philipp Stephani <p.stephani2 <at> gmail.com>
> > >  > Date: Sun, 16 Oct 2016 18:25:08 +0000

It's hard to have a useful discussion when messages are several months
apart.

> > >  The patch for the ELisp manual simply rearranges the same words, so
> > >  it's not clear to me why we would prefer it to what's already there.
> > >
> > > I don't think there's any repetition or rearranging here.
> >
> > Here's the ELisp manual part of your proposed change:
> >
> >    If the mode command is called from Lisp (i.e., non-interactively), it
> >   -should enable the mode if the argument is omitted or @code{nil}; it
> >   -should toggle the mode if the argument is the symbol @code{toggle};
> >   -otherwise it should treat the argument in the same way as for an
> >   -interactive call with a numeric prefix argument, as described above.
> >   +should toggle the mode if the argument is the symbol @code{toggle}; it
> >   +should disable the mode if the argument is a non-positive integer;
> >   +otherwise, e.g., if the argument is omitted or nil or a positive
> >   +integer, it should enable the mode.
> >
> > Don't you agree that it does little apart of re-shuffling the same
> > words?
> 
> It also describes what happens when the argument is neither nil nor
> `toggle' nor an integer. That is currently unspecified, or rather
> implicitly specified by the observable (but unspecified) behavior of
> `prefix-numeric-value'.

I think the "otherwise" part describes that.

> > > The key difference is that when called from Lisp with an
> > > argument that is neither nil nor an integer, the mode is also enabled.
> >
> > Why would we want to require that?  This subsection describes the
> > conventions, it doesn't describe the effect of certain popular
> > implementation of those conventions, because we don't really want to
> > _require_ modes to behave in any way beyond the described behavior.
> 
> This isn't about the implementation but the interface, i.e. the
> observable behavior of minor mode functions.

I don't see how making this the matter of interface changes anything.
We still don't want to require modes to interpret the interface the
way you'd like to see.

Bottom line: I think there's nothing important left to discuss here.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 24706-done <at> debbugs.gnu.org, Philipp Stephani <p.stephani2 <at> gmail.com>,
 drew.adams <at> oracle.com
Subject: Re: bug#24706: 26.0.50; Minor mode functions should do strict
 argument type checking
Date: Thu, 1 Oct 2020 05:12:49 -0700

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Philipp Stephani <p.stephani2 <at> gmail.com>
>> Date: Sat, 1 Aug 2020 22:47:03 +0200
>> Cc: Drew Adams <drew.adams <at> oracle.com>, 24706 <at> debbugs.gnu.org
>>
>> Am Mi., 26. Apr. 2017 um 13:27 Uhr schrieb Eli Zaretskii <eliz <at> gnu.org>:
>> >
>> > > From: Philipp Stephani <p.stephani2 <at> gmail.com>
>> > > Date: Sun, 23 Apr 2017 17:51:32 +0000
>> > > Cc: drew.adams <at> oracle.com, 24706 <at> debbugs.gnu.org
>> > >
>> > > Eli Zaretskii <eliz <at> gnu.org> schrieb am So., 16. Okt. 2016 um 20:51 Uhr:
>> > >
>> > >  > From: Philipp Stephani <p.stephani2 <at> gmail.com>
>> > >  > Date: Sun, 16 Oct 2016 18:25:08 +0000
>
> It's hard to have a useful discussion when messages are several months
> apart.
>
>> > >  The patch for the ELisp manual simply rearranges the same words, so
>> > >  it's not clear to me why we would prefer it to what's already there.
>> > >
>> > > I don't think there's any repetition or rearranging here.
>> >
>> > Here's the ELisp manual part of your proposed change:
>> >
>> >    If the mode command is called from Lisp (i.e., non-interactively), it
>> >   -should enable the mode if the argument is omitted or @code{nil}; it
>> >   -should toggle the mode if the argument is the symbol @code{toggle};
>> >   -otherwise it should treat the argument in the same way as for an
>> >   -interactive call with a numeric prefix argument, as described above.
>> >   +should toggle the mode if the argument is the symbol @code{toggle}; it
>> >   +should disable the mode if the argument is a non-positive integer;
>> >   +otherwise, e.g., if the argument is omitted or nil or a positive
>> >   +integer, it should enable the mode.
>> >
>> > Don't you agree that it does little apart of re-shuffling the same
>> > words?
>>
>> It also describes what happens when the argument is neither nil nor
>> `toggle' nor an integer. That is currently unspecified, or rather
>> implicitly specified by the observable (but unspecified) behavior of
>> `prefix-numeric-value'.
>
> I think the "otherwise" part describes that.
>
>> > > The key difference is that when called from Lisp with an
>> > > argument that is neither nil nor an integer, the mode is also enabled.
>> >
>> > Why would we want to require that?  This subsection describes the
>> > conventions, it doesn't describe the effect of certain popular
>> > implementation of those conventions, because we don't really want to
>> > _require_ modes to behave in any way beyond the described behavior.
>>
>> This isn't about the implementation but the interface, i.e. the
>> observable behavior of minor mode functions.
>
> I don't see how making this the matter of interface changes anything.
> We still don't want to require modes to interpret the interface the
> way you'd like to see.
>
> Bottom line: I think there's nothing important left to discuss here.

That was 8 weeks ago, and there has been no further comments.  I'm
therefore closing this bug now.

If there is anything more to do here, please reply to this email (use
"Reply to all" in your email client) and we can reopen the bug report.

Best regards,
Stefan Kangas

Previous Next

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