GNU bug report logs - #41727
26.3; Doc of `define-minor-mode' and minor-mode commands

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 41727 in the body.
You can then email your comments to 41727 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: 26.3; Doc of `define-minor-mode' and minor-mode commands
Date: Fri, 5 Jun 2020 13:39:27 -0700 (PDT)

The doc needs improvement when describing calling the mode from Lisp.

1. The doc string of `define-minor-mode' says this:

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

   This is wrong (incomplete).  It disables the mode if the
   `prefix-numeric-value' of ARG <= 0, not if ARG is a non-positive
   integer.  The code does this: (prefix-numeric-value arg).  So if you
   pass the symbol `-' as ARG then the mode is disabled.

1. The (default) doc string produced by `define-minor-mode' says this:

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

   Again, this is wrong (incomplete).  It doesn't say that if ARG is
   non-nil other than `toggle' then disable the mode if the
   `prefix-numeric-value' of ARG <= 0, and enable it if the
   `prefix-numeric-value' of ARG > 0.

3. The Elisp manual doc says this (node `Defining Minor Modes'):

     From Lisp, an argument of 'toggle' toggles the mode, whereas an
     omitted or 'nil' argument enables the mode.

   Again, this is wrong (incomplete).

   * It says nothing about how the mode is disabled when called from
     Lisp.  It should say that an ARG whose `prefix-numeric-value' is
     non-positive disables the mode.

   * It should say that an ARG whose `prefix-numeric-value' is
     non-positive enables the mode.


In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.18362
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

From: Drew Adams <drew.adams <at> oracle.com>
To: 41727 <at> debbugs.gnu.org
Subject: RE: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Fri, 5 Jun 2020 17:01:45 -0700 (PDT)

For the (default) doc string of a minor mode,
I think something like this should take care of it.

 Interactively, toggle the mode.  But with a prefix arg, enable the
 mode if the numeric value is positive, and disable it otherwise.

 If called from Lisp, toggle the mode if the optional arg is 'toggle'.
 Otherwise, handle it as the prefix arg: disable the mode if
 `prefix-numeric-value' of the arg is non-positive, and enable it
 otherwise.  This implies that if the arg is nil or absent then enable
 the mode.
___

Ideally, we would have a way to provide a custom doc
string that also included this info somehow.

Maybe the doc string of `define-minor-mode' could
show the default doc string and suggest that if you
provide your own doc string you include the same or
similar information, if appropriate.

(And it might generally be good if the Lisp info were
at the end of the doc string.)

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 41727 <at> debbugs.gnu.org
Subject: Re: bug#41727: 26.3;
 Doc of `define-minor-mode' and minor-mode commands
Date: Sat, 06 Jun 2020 09:13:53 +0300

> Date: Fri, 5 Jun 2020 13:39:27 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> 
> The doc needs improvement when describing calling the mode from Lisp.
> 
> 1. The doc string of `define-minor-mode' says this:
> 
>      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).

It actually says this:

  Interactively with no prefix argument, it toggles the mode.
  A prefix argument enables the mode if the argument is positive,
  and disables it otherwise.

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


> 3. The Elisp manual doc says this (node `Defining Minor Modes'):
> 
>      From Lisp, an argument of 'toggle' toggles the mode, whereas an
>      omitted or 'nil' argument enables the mode.

It actually says this:

     The toggle command takes one optional (prefix) argument.  If called
     interactively with no argument it toggles the mode on or off.  A
     positive prefix argument enables the mode, any other prefix
     argument disables it.  From Lisp, an argument of ‘toggle’ toggles
     the mode, whereas an omitted or ‘nil’ argument enables the mode.

Are you reading obsolete docs?

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41727 <at> debbugs.gnu.org
Subject: RE: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Sat, 6 Jun 2020 09:45:46 -0700 (PDT)

> > The doc needs improvement when describing calling the mode from Lisp.
> >
> > 1. The doc string of `define-minor-mode' says this:
> >
> >      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).
> 
> It actually says this:
>   Interactively with no prefix argument, it toggles the mode.
>   A prefix argument enables the mode if the argument is positive,
>   and disables it otherwise.
> 
>   <snipped: verbatim quote of the text I cited about Lisp call>

Yes, and?  The point was about what the doc says about
a call from Lisp.

> > 3. The Elisp manual doc says this (node `Defining Minor Modes'):
> >
> >      From Lisp, an argument of 'toggle' toggles the mode, whereas an
> >      omitted or 'nil' argument enables the mode.
> 
> It actually says this:
>      The toggle command takes one optional (prefix) argument.  If called
>      interactively with no argument it toggles the mode on or off.  A
>      positive prefix argument enables the mode, any other prefix
>      argument disables it.
>
>      <snipped: verbatim quote of the text I cited about Lisp call>

Yes, and?  The point was about what the doc says about
a call from Lisp.

The bug report doesn't find fault with the description of
the interactive behavior.

And my follow-up message suggests text for the doc string
that I think is accurate and complete, and it improves the
description of the interactive handling as well.

The bug report is about the content/message/info, though,
not the wording.  If you don't like the wording of my
suggestion, some other wording that provides as accurate
and complete a description will be fine.  Thx.

> Are you reading obsolete docs?

I'm reading the 26.3 docs, as suggested by the report:

In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.18362
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 41727 <at> debbugs.gnu.org
Subject: Re: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Sat, 06 Jun 2020 21:56:30 +0300

> Date: Sat, 6 Jun 2020 09:45:46 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 41727 <at> debbugs.gnu.org
> 
> > > The doc needs improvement when describing calling the mode from Lisp.
> > >
> > > 1. The doc string of `define-minor-mode' says this:
> > >
> > >      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).
> > 
> > It actually says this:
> >   Interactively with no prefix argument, it toggles the mode.
> >   A prefix argument enables the mode if the argument is positive,
> >   and disables it otherwise.
> > 
> >   <snipped: verbatim quote of the text I cited about Lisp call>
> 
> Yes, and?  The point was about what the doc says about
> a call from Lisp.

My point was that you take the text out of its context, and that
context spells out what you say is missing.

This is not the first time you raise this issue, and the argument
always goes the same way.  I wish you'd stopped these repeated
complaints about the same thing.

> > Are you reading obsolete docs?
> 
> I'm reading the 26.3 docs, as suggested by the report:

The latest sources seem to be different.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 41727 <at> debbugs.gnu.org
Subject: RE: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Sat, 6 Jun 2020 13:39:30 -0700 (PDT)

> My point was that you take the text out of its context, and that
> context spells out what you say is missing.

No, it does not.  It does not at all say what I say
is missing from the description of the Lisp-call
behavior.

> This is not the first time you raise this issue, and the argument
> always goes the same way.  I wish you'd stopped these repeated
> complaints about the same thing.

I've never made such a "complaint" before.  Please
point to one such, if you think doing so really adds
value here.

Or is your effort only to argue ad hominem, as if
I'm doing something bad, and have done it "repeated"ly?
How about addressing the actual bug report?

You tell me how the existing text (cited by both you and
me) correctly and completely describes the Lisp behavior.
Passing symbol `-' isn't passing an integer, and so on.

Now, if you just don't want to fix the text, that's
another story.  But I think you'll find it hard to argue
that the report is mistaken and the text is accurate and
complete.

And I hope you realize that the handling of the arg to
`define-minor-mode' has been the subject of a fair amount
of confusion.  There have been several attempts to improve
the doc.  But it's still not as clear and helpful as it
should be.  And the fix is simple: say the missing bits
wrt the Lisp case.

> > > Are you reading obsolete docs?
> >
> > I'm reading the 26.3 docs, as suggested by the report:
> 
> The latest sources seem to be different.

Different from what?  I stated that what you wrote
is exactly the text I was referring to, verbatim.
You simply added the text about the interactive
case.  AFAICT, we're talking about exactly the same
text, in the same release, 26.3.

I wonder if you're actually reading what I wrote.

The text you quote is exactly the text that suffers
from the problem I raised.  The text about the
interactive case in no way helps describe the missing
parts of the case for the Lisp behavior.

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

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 41727 <at> debbugs.gnu.org
Subject: Re: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Sun, 07 Jun 2020 12:04:10 +0200

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

> Ideally, we would have a way to provide a custom doc
> string that also included this info somehow.

Are you aware of `easy-mmode--arg-docstring'?

Michael.

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

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41727 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Sun, 07 Jun 2020 12:08:07 +0200

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

> My point was that you take the text out of its context, and that
> context spells out what you say is missing.

Just to be sure: you both speak about the sign of the ARG (current text)
vs. the sign of (prefix-numeric-value ARG) (as Drew wants)?  AFAIU Drew
wants to mention that even in the noninteractive case
`prefix-numeric-value' is called on the ARG before testing it.

Michael.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 41727 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Sun, 07 Jun 2020 17:31:50 +0300

> From: Michael Heerdegen <michael_heerdegen <at> web.de>
> Cc: Drew Adams <drew.adams <at> oracle.com>,  41727 <at> debbugs.gnu.org
> Date: Sun, 07 Jun 2020 12:08:07 +0200
> 
> AFAIU Drew wants to mention that even in the noninteractive case
> `prefix-numeric-value' is called on the ARG before testing it.

If that's the essence of the bug report (and I indeed didn't realize
that), then I don't think it's a good idea to document this quirk.  It
looks like an implementation detail to me, if not an outright bug that
should be fixed.

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

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41727 <at> debbugs.gnu.org
Subject: Re: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Sun, 07 Jun 2020 16:45:21 +0200

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

> If that's the essence of the bug report (and I indeed didn't realize
> that), then I don't think it's a good idea to document this quirk.  It
> looks like an implementation detail to me, if not an outright bug that
> should be fixed.

I'm undecided.  It means at least that passing an unevaluated prefix arg
to the function "works", which may matter in some cases.

Michael.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 41727 <at> debbugs.gnu.org
Subject: RE: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Sun, 7 Jun 2020 09:06:21 -0700 (PDT)

> > Ideally, we would have a way to provide a custom doc
> > string that also included this info somehow.
> 
> Are you aware of `easy-mmode--arg-docstring'?

No.  I've never looked at (or heard of) `easy-mmode'.
Thanks.

But now that I look at it, in Emacs 26.3, I see
no `easy-mmode--arg-docstring'.  What am I missing?

(BTW, easy-mmode.el uses both "docstring" and
"doc-string" as a noun in its doc.  Emacs should
pick one or the other.  IMHO, it should really
probably pick "doc string", whatever it picks it
should use pretty much everywhere.)

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Michael Heerdegen <michael_heerdegen <at> web.de>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 41727 <at> debbugs.gnu.org
Subject: RE: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Sun, 7 Jun 2020 09:08:06 -0700 (PDT)

> > My point was that you take the text out of its context, and that
> > context spells out what you say is missing.
> 
> Just to be sure: you both speak about the sign of the ARG (current text)
> vs. the sign of (prefix-numeric-value ARG) (as Drew wants)?  AFAIU Drew
> wants to mention that even in the noninteractive case
> `prefix-numeric-value' is called on the ARG before testing it.

Yes, it's the raw prefix arg (or equivalent) that's
used, in all cases.  And that's not necessarily an
integer.  And `prefix-numeric-value' is applied to
that, to get the effective arg that's used.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 41727 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: RE: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Sun, 7 Jun 2020 09:16:25 -0700 (PDT)

> > AFAIU Drew wants to mention that even in the noninteractive case
> > `prefix-numeric-value' is called on the ARG before testing it.
> 
> If that's the essence of the bug report (and I indeed didn't realize
> that), then I don't think it's a good idea to document this quirk.  It
> looks like an implementation detail to me, if not an outright bug that
> should be fixed.

If you don't document it then users won't know how
to use it correctly from Lisp (at least not without
studying the code).

That's misleading enough to make me wonder whether,
in that case, it might be better to say nothing at
all about the call-from-Lisp case, forcing Lisp
users to consult the code.

My preference is (obviously) to have the doc tell
the whole story: accurate & complete.

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

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 41727 <at> debbugs.gnu.org
Subject: Re: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Sun, 07 Jun 2020 18:19:59 +0200

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

> > Are you aware of `easy-mmode--arg-docstring'?
>
> No.  I've never looked at (or heard of) `easy-mmode'.

Isn't `define-minor-mode' defined in "easy-mmode.el"?

> But now that I look at it, in Emacs 26.3, I see
> no `easy-mmode--arg-docstring'.  What am I missing?

I guess that's one version to small.  It had been introduced when
discussing Bug#10754.  I can send you current master's version of the
file offlist if you want.  AFAIU it's the variable you asked for.

Michael.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 41727 <at> debbugs.gnu.org
Subject: RE: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Sun, 7 Jun 2020 09:30:14 -0700 (PDT)

> > > Are you aware of `easy-mmode--arg-docstring'?
> >
> > No.  I've never looked at (or heard of) `easy-mmode'.
> 
> Isn't `define-minor-mode' defined in "easy-mmode.el"?

Yes.  I guess I meant that I haven't looked at much
in that file.

> > But now that I look at it, in Emacs 26.3, I see
> > no `easy-mmode--arg-docstring'.  What am I missing?
> 
> I guess that's one version to small.  It had been introduced when
> discussing Bug#10754.  I can send you current master's version of the
> file offlist if you want.  AFAIU it's the variable you asked for.

I have the 27 pretest, so I have (at least some version)
of `easy-mmode--arg-docstring'; thx.

Yes, that's presumably what I suggest should be changed.

And I guess where that Lisp info gets inserted could be
reconsidered.  This bug report suggests maybe putting it
at the end of the doc string.  Most calls of a minor-mode
command will be interactive.  And I'm arguing in favor of
making the Lisp description of ARG more correct/complete.
Perhaps, especially if that's done, it makes sense to
relegate such info to the end.

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

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 41727 <at> debbugs.gnu.org
Subject: Re: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Mon, 08 Jun 2020 19:16:24 +0200

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

> That's misleading enough to make me wonder whether,
> in that case, it might be better to say nothing at
> all about the call-from-Lisp case, forcing Lisp
> users to consult the code.

How about leaving only cases like ARG -> '- undocumented?

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

Good enough for daily business.  And we are lucky: since an additional
`prefix-numeric-value' doesn't harm (it's idempotent), it's not a
problem if it's called on the arg before passing it to the mode function
and by the mode function again.

Michael.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 41727 <at> debbugs.gnu.org
Subject: RE: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Mon, 8 Jun 2020 10:38:43 -0700 (PDT)

> > That's misleading enough to make me wonder whether,
> > in that case, it might be better to say nothing at
> > all about the call-from-Lisp case, forcing Lisp
> > users to consult the code.
> 
> How about leaving only cases like ARG -> '- undocumented?
> 
>   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 if the argument is a positive integer or
>   omitted or nil.

That's what we say now, and the reason I filed the bug.

> Good enough for daily business.  ...

Not good enough for me. ;-)

Consider a case where some command A invokes a minor-mode
command B, to turn B on or off for some purpose/extent.
Consider the case where A's prefix arg is passed to B, to
do that.

The programmer writing the Lisp code to define A should
know that s?he can just pass the raw prefix arg.  The
resulting code will be simpler, easier to read, etc.

I see no reason at all why we wouldn't provide an accurate
(complete) description of what ARG is for Lisp use.

What do we gain by not doing this right?

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

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 41727 <at> debbugs.gnu.org
Subject: Re: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Tue, 09 Jun 2020 09:58:32 +0200

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

> > How about leaving only cases like ARG -> '- undocumented?
> >
> >   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 if the argument is a positive integer or
> >   omitted or nil.
>
> That's what we say now, and the reason I filed the bug.

No, it's not, it doesn't contradict the implementation.  Did you read
carefully?

> Consider a case where some command A invokes a minor-mode
> command B, to turn B on or off for some purpose/extent.
> Consider the case where A's prefix arg is passed to B, to
> do that.
>
> The programmer writing the Lisp code to define A should
> know that s?he can just pass the raw prefix arg.  The
> resulting code will be simpler, easier to read, etc.

We don't know if the original author intended the semantics of the
documentation or of the implementation.  If we are sure the current
implementation is what was intended I would be ok with documenting it,
but it's really far from important IMHO.

I leave it to Eli to decide.

Michael.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 41727 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Tue, 09 Jun 2020 17:39:33 +0300

> From: Michael Heerdegen <michael_heerdegen <at> web.de>
> Cc: Eli Zaretskii <eliz <at> gnu.org>,  41727 <at> debbugs.gnu.org
> Date: Tue, 09 Jun 2020 09:58:32 +0200
> 
> We don't know if the original author intended the semantics of the
> documentation or of the implementation.  If we are sure the current
> implementation is what was intended I would be ok with documenting it,
> but it's really far from important IMHO.
> 
> I leave it to Eli to decide.

I stated my opinion.

Do we have other places where a function called from Lisp uses the
prefix arg in any similar way?  It seems bad practice to me:
non-interactive calls shouldn't use interactive features.

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

From: Michael Heerdegen <michael_heerdegen <at> web.de>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41727 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Tue, 09 Jun 2020 17:21:15 +0200

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

> Do we have other places where a function called from Lisp uses the
> prefix arg in any similar way?

Seems so, e.g.

allout-kill-line, allout-yank-pop, dired-do-kill-lines,
doc-view-scroll-up-or-next-page, doc-view-scroll-down-or-previous-page,
follow-scroll-up-arg, .... there are lots of more examples.

The feature we are discussing in this report is also already used, see
`toggle-menu-bar-mode-from-frame' for an example.

> It seems bad practice to me: non-interactive calls shouldn't use
> interactive features.

Dunno.  OTOH, most commands using the prefix arg don't distinguish
between interactive and noninteractive calls.  Why should
`define-minor-mode' describe the two cases separately?


Michael.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 41727 <at> debbugs.gnu.org
Subject: RE: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Tue, 9 Jun 2020 08:40:12 -0700 (PDT)

> > > How about leaving only cases like ARG -> '- undocumented?
> > >
> > >   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 if the argument is a
> > >   positive integer or omitted or nil.
> >
> > That's what we say now, and the reason I filed the bug.
> 
> No, it's not, it doesn't contradict the implementation.  Did you read
> carefully?

I think I did.  We don't use exactly the same words, but
I think we do say just that.

  When called from Lisp, the mode command toggles the mode if the
  argument is `toggle', 

Verbatim the same.

  disables the mode if the argument is a non-positive integer,

Verbatim the same.

  and enables the mode otherwise (including
  if the argument is omitted or nil or a positive integer).

OK, your text doesn't say "otherwise".  Your text is less
exact, since the "otherwise" is correct - omitted/nil and
positive integer constitute a subset of what's true.

Is that really your suggestion, to not document that
something other than omitted, nil and a positive integer
enables the mode?  To me, that would be a step backward,
not forward.  That doesn't correspond to what the code does.

> > Consider a case where some command A invokes a minor-mode
> > command B, to turn B on or off for some purpose/extent.
> > Consider the case where A's prefix arg is passed to B, to
> > do that.
> >
> > The programmer writing the Lisp code to define A should
> > know that s?he can just pass the raw prefix arg.  The
> > resulting code will be simpler, easier to read, etc.
> 
> We don't know if the original author intended the semantics of the
> documentation or of the implementation.  If we are sure the current
> implementation is what was intended I would be ok with documenting it,
> but it's really far from important IMHO.

Until the code is changed, e.g. because someone thinks
the behavior is wrong, the doc should reflect it.  I,
for one, think the behavior is OK as is.  The use case
I just gave (cited above) is one argument for it.

Many commands have the `interactive' form massage the
prefix arg, to present something a bit different to
the body.  E.g., a change from raw to numeric prefix
value is done in the `interactive' form, for whatever
reason.

This command doesn't work that way.  Instead, what is
passed to Lisp is the raw prefix arg, and it is the
body (which also corresponds to a non-interactive call)
that converts that to a numeric value.

Someone (and `d-m-mode' has been worked over more than
once wrt its interactive-vs-Lisp behavior, I believe)
presumably deliberately decided that this command
should act differently.

Many commands (most, I think) make it so that the body
gets just what it needs, and any compensation for
interactivity is taken care of only in the `interactive'
spec.  Someone presumably thought this command should
be an exception in that regard.

Until someone decides otherwise, and changes the
behavior (which I doubt will happen, in particular
because of backward incompatibility), IMO it's the doc
that needs to be changed to fit the behavior, not the
other way around.

I don't understand the hesitation to make the doc say
just what the truth is.  It doesn't take any more text.
I already suggested wording, and I made clear that
other wording that says the same thing (describes the
behavior accurately) would be fine instead.

What's the pushback, here?  Why shouldn't we make the
doc tell the real story wrt the ARG that Lisp expects?

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Michael Heerdegen <michael_heerdegen <at> web.de>
Cc: 41727 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: RE: bug#41727: 26.3; Doc of `define-minor-mode' and minor-mode
 commands
Date: Tue, 9 Jun 2020 08:51:07 -0700 (PDT)

> Do we have other places where a function called from Lisp uses the
> prefix arg in any similar way?  It seems bad practice to me:
> non-interactive calls shouldn't use interactive features.

I actually agree with what you say there.

I don't know why this was designed as an
exception.  But I think it was.

There has been discussion over the years
about the interactive vs Lisp behavior of
`d-m-mode' and the confusion of users, and
I think the behavior may even have changed
over time.

I think Stefan might know why this does
what it does.

I don't know why it does - but it does.
Do you see the behavior changing to fit the
more common model, as you suggest?  If so,
OK (but that will break some existing code
out there).

If you don't expect to fix the behavior, to
no longer have the "bad practice" you cite,
then, until we do fix it, (IMO) we should
fix the doc to fit the behavior.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 41727-done <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#41727: 26.3;
 Doc of `define-minor-mode' and minor-mode commands
Date: Sat, 25 Sep 2021 08:41:08 -0700

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

>> Date: Sat, 6 Jun 2020 09:45:46 -0700 (PDT)
>> From: Drew Adams <drew.adams <at> oracle.com>
>> Cc: 41727 <at> debbugs.gnu.org
>>
>> > > The doc needs improvement when describing calling the mode from Lisp.
>> > >
>> > > 1. The doc string of `define-minor-mode' says this:
>> > >
>> > >      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).
>> >
>> > It actually says this:
>> >   Interactively with no prefix argument, it toggles the mode.
>> >   A prefix argument enables the mode if the argument is positive,
>> >   and disables it otherwise.
>> >
>> >   <snipped: verbatim quote of the text I cited about Lisp call>
>>
>> Yes, and?  The point was about what the doc says about
>> a call from Lisp.
>
> My point was that you take the text out of its context, and that
> context spells out what you say is missing.
>
> This is not the first time you raise this issue, and the argument
> always goes the same way.  I wish you'd stopped these repeated
> complaints about the same thing.
>
>> > Are you reading obsolete docs?
>>
>> I'm reading the 26.3 docs, as suggested by the report:
>
> The latest sources seem to be different.

This bug report is sprawling, and it is very hard to make heads or tails
of what is being discussed.  One initial issue is that the bug report
was made against the text in 26.3, which has changed significantly on
current master.

In any case, Eli seems to be of the opinion that no further change is
needed here.  I tend to agree, and I'm therefore closing this bug
report.

If there are still any outstanding issues, please carefully review the
text that we currently have on master and report any issues separately
based on that.  Otherwise, it will be very hard to make any progress.
Thanks in advance.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>, Eli Zaretskii <eliz <at> gnu.org>
Cc: "41727-done <at> debbugs.gnu.org" <41727-done <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#41727: 26.3; Doc of `define-minor-mode' and
 minor-mode commands
Date: Sat, 25 Sep 2021 16:58:33 +0000

> This bug report is sprawling, and it is very hard to make heads or
> tails of what is being discussed.

I don't think that's the case.  Of course it takes
time to read and understand a bug thread.

> In any case, Eli seems to be of the opinion that
> no further change is needed here.

Eli was the one who said (and I agreed):

  Do we have other places where a function called
  from Lisp uses the prefix arg in any similar way?

  It seems bad practice to me: non-interactive calls
  shouldn't use interactive features.

That's about the code behavior, not about the doc
string.  But especially given that unusual (per Eli)
behavior, I think the doc string should make clear
what the behavior is (for Lisp use).  It's not the
usual behavior for Lisp use.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: stefan <at> marxist.se, 41727 <at> debbugs.gnu.org
Subject: Re: [External] : Re: bug#41727: 26.3; Doc of `define-minor-mode' and
 minor-mode commands
Date: Sat, 25 Sep 2021 20:18:10 +0300

> From: Drew Adams <drew.adams <at> oracle.com>
> CC: "41727-done <at> debbugs.gnu.org" <41727-done <at> debbugs.gnu.org>
> Date: Sat, 25 Sep 2021 16:58:33 +0000
> Accept-Language: en-US
> 
> > This bug report is sprawling, and it is very hard to make heads or
> > tails of what is being discussed.
> 
> I don't think that's the case.  Of course it takes
> time to read and understand a bug thread.
> 
> > In any case, Eli seems to be of the opinion that
> > no further change is needed here.
> 
> Eli was the one who said (and I agreed):
> 
>   Do we have other places where a function called
>   from Lisp uses the prefix arg in any similar way?
> 
>   It seems bad practice to me: non-interactive calls
>   shouldn't use interactive features.
> 
> That's about the code behavior, not about the doc
> string.

Exactly.

>         But especially given that unusual (per Eli)
> behavior, I think the doc string should make clear
> what the behavior is (for Lisp use).

No, that doesn't follow.

Stefan is right: this bug should be closed.

Previous Next

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