GNU bug report logs - #52007
26.3; Doc of `define-globalized-minor-mode' and global(ized) minor modes

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 52007 in the body.
You can then email your comments to 52007 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" <bug-gnu-emacs <at> gnu.org>
Subject: 26.3; Doc of `define-globalized-minor-mode' and global(ized) minor
 modes
Date: Sat, 20 Nov 2021 22:44:23 +0000

AFAICT, neither the doc strings nor the Elisp manual (node `Defining
Minor Modes') tells you how, from Lisp, to turn OFF a global(ized) minor
mode.  It tells you how to turn it ON from Lisp, and it tells you that
you can use the Customize UI to turn it on and off.  But it doesn't tell
you how to turn it OFF, i.e., to turn off the mode in all buffers.

The doc for a globalized minor mode `foo-mode' says this:

  With prefix ARG, enable Global-Foo mode if ARG is positive;
  otherwise, disable it.  If called from Lisp, enable the mode if
  ARG is omitted or nil.

The first sentence describes the interactive behavior.  The second tells
you how to turn it ON from Lisp.  How to turn it off?  The doc should at
least make a connection between the prefix-arg value and the Lisp arg.

Please fix this.  It should be clear from the docs how to turn the mode
off everywhere, as well as on everywhere.  This can even be important if
some defcustom has a :set that needs to, e.g., turn it off everywhere
and then turn the mode back on wherever it was on.

Turning on `debug-on-entry' for a global(ized) minor mode, and then
using the Customize UI to toggle its option, a user can discover an arg
they can pass with Lisp to turn it off.  But users shouldn't need to
jump through such hoops to find out how to turn it off.

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.19042
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Drew Adams <drew.adams <at> oracle.com>, "52007 <at> debbugs.gnu.org"
 <52007 <at> debbugs.gnu.org>
Subject: RE: 26.3; Doc of `define-globalized-minor-mode' and global(ized)
 minor modes
Date: Sat, 20 Nov 2021 23:17:49 +0000

It's even worse than I thought.

The first line of the doc string of the globalized
version of minor mode `foo-mode' (`global-foo-mode')
says that it toggles `foo-mode' everywhere:

  Toggle Foo mode in all buffers.

It doesn't do that at all.  Instead, it toggles
`global-foo-mode'.  BIG difference.  If `foo-mode'
is ON in buffer B1 and OFF in buffer B2, then
toggling `foo-mode' everywhere would result in
`foo-mode' being OFF in B1 and ON in B2.

What instead happens is that if the global mode was
OFF then `global-foo-mode' is turned ON, which turns
ON `foo-mode' in all buffers.  And if the global
mode was ON then it is turned OFF, which turns OFF
`foo-mode' in all buffers.

We don't seem to have a command that toggles a minor
mode in all buffers, that is, flips its state ON/OFF.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 52007-done <at> debbugs.gnu.org
Subject: Re: bug#52007: 26.3;
 Doc of `define-globalized-minor-mode' and global(ized) minor modes
Date: Sun, 21 Nov 2021 08:41:13 +0200

> From: Drew Adams <drew.adams <at> oracle.com>
> Date: Sat, 20 Nov 2021 22:44:23 +0000
> 
> The doc for a globalized minor mode `foo-mode' says this:
> 
>   With prefix ARG, enable Global-Foo mode if ARG is positive;
>   otherwise, disable it.  If called from Lisp, enable the mode if
>   ARG is omitted or nil.

You are looking at an old Emacs.  Emacs 28 says:

  With prefix ARG, enable Global Display-Line-Numbers mode if ARG is
  positive; otherwise, disable it.

  If called from Lisp, toggle the mode if ARG is ‘toggle’.
  Enable the mode if ARG is nil, omitted, or is a positive number.
  Disable the mode if ARG is a negative number.

So this is already fixed, and I'm closing this bug.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 52007 <at> debbugs.gnu.org
Subject: Re: bug#52007: 26.3;
 Doc of `define-globalized-minor-mode' and global(ized) minor modes
Date: Sun, 21 Nov 2021 08:42:04 +0200

> From: Drew Adams <drew.adams <at> oracle.com>
> Date: Sat, 20 Nov 2021 23:17:49 +0000
> 
> It's even worse than I thought.
> 
> The first line of the doc string of the globalized
> version of minor mode `foo-mode' (`global-foo-mode')
> says that it toggles `foo-mode' everywhere:
> 
>   Toggle Foo mode in all buffers.
> 
> It doesn't do that at all.  Instead, it toggles
> `global-foo-mode'.

No, it turns ON both foo-mode and global-foo-mode.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: "52007 <at> debbugs.gnu.org" <52007 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#52007: 26.3; Doc of
 `define-globalized-minor-mode' and global(ized) minor modes
Date: Sun, 21 Nov 2021 17:22:30 +0000

> > It's even worse than I thought.
> >
> > The first line of the doc string of the globalized
> > version of minor mode `foo-mode' (`global-foo-mode')
> > says that it toggles `foo-mode' everywhere:
> >
> >   Toggle Foo mode in all buffers.
> >
> > It doesn't do that at all.  Instead, it toggles
> > `global-foo-mode'.
> 
> No, it turns ON both foo-mode and global-foo-mode.

You missed the point of the bug report.
Toggling the global mode turns them both on (or off,
depending on the current value of `global-foo-mode')
in all buffers, yes.

That's not what it means to toggle `foo-mode'
everywhere.  Doing that would flip the value that
`foo-mode' (non-global mode) has in each buffer.

Correcting the doc to say that it toggles the
global mode was correct.  Saying that it toggles
the local mode everywhere was incorrect.

Glad this will be fixed in Emacs 28.  (And no, I
wasn't "looking at an old Emacs".  I reported on
the latest Emacs release, Emacs 27.2.)

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 52007 <at> debbugs.gnu.org
Subject: Re: [External] : Re: bug#52007: 26.3; Doc of
 `define-globalized-minor-mode' and global(ized) minor modes
Date: Sun, 21 Nov 2021 19:28:40 +0200

> From: Drew Adams <drew.adams <at> oracle.com>
> CC: "52007 <at> debbugs.gnu.org" <52007 <at> debbugs.gnu.org>
> Date: Sun, 21 Nov 2021 17:22:30 +0000
> 
> > >   Toggle Foo mode in all buffers.
> > >
> > > It doesn't do that at all.  Instead, it toggles
> > > `global-foo-mode'.
> > 
> > No, it turns ON both foo-mode and global-foo-mode.
> 
> You missed the point of the bug report.
> Toggling the global mode turns them both on (or off,
> depending on the current value of `global-foo-mode')
> in all buffers, yes.

No.  It turns on foo-mode in all buffers, and it turns on
global-foo-mode globally -- it is nonsense to talk about "global mode
in a buffer", because global modes are, well, global.

> That's not what it means to toggle `foo-mode'
> everywhere.  Doing that would flip the value that
> `foo-mode' (non-global mode) has in each buffer.

And it does.

> Glad this will be fixed in Emacs 28.  (And no, I
> wasn't "looking at an old Emacs".  I reported on
> the latest Emacs release, Emacs 27.2.)

Your report said 26.3.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: "52007 <at> debbugs.gnu.org" <52007 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#52007: 26.3; Doc of
 `define-globalized-minor-mode' and global(ized) minor modes
Date: Sun, 21 Nov 2021 17:45:53 +0000

> > > >   Toggle Foo mode in all buffers.
> > > >
> > > > It doesn't do that at all.  Instead, it toggles
> > > > `global-foo-mode'.
> > >
> > > No, it turns ON both foo-mode and global-foo-mode.
> >
> > You missed the point of the bug report.
> > Toggling the global mode turns them both on (or off,
> > depending on the current value of `global-foo-mode')
> > in all buffers, yes.
> 
> No.  It turns on foo-mode in all buffers, and it turns on
> global-foo-mode globally -- it is nonsense to talk about "global mode
> in a buffer", because global modes are, well, global.

We agree about what it does, however you prefer
to describe it.

> > That's not what it means to toggle `foo-mode'
> > everywhere.  Doing that would flip the value that
> > `foo-mode' (non-global mode) has in each buffer.
> 
> And it does.

It does not.  If `foo-mode' is on in buffer A, and
the global mode is off, then toggling the global mode
results in `foo-mode' being (still) on in buffer A.

Toggling `foo-mode' in all buffers (which is what
the erroneous doc string said) would turn it on where
it is off and off where it is on.  It would turn it
off in buffer A.  It does not do so; it doesn't
toggle `foo-mode' in each buffer; instead, it turns
the mode on everywhere or off everywhere, depending
on the value of `global-foo-mode'.

> > Glad this will be fixed in Emacs 28.  (And no, I
> > wasn't "looking at an old Emacs".  I reported on
> > the latest Emacs release, Emacs 27.2.)
> 
> Your report said 26.3.

Ah, yes, you're right.  Mea culpa.  I can't use Emacs
27 in general (broken with my setup), and I forgot to
switch to emacs -Q with Emacs 27.2 to file this
particular bug.

But as you've acknowledged, the bug exists in 27.2,
the latest Emacs release.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 52007 <at> debbugs.gnu.org
Subject: Re: [External] : Re: bug#52007: 26.3; Doc of
 `define-globalized-minor-mode' and global(ized) minor modes
Date: Sun, 21 Nov 2021 20:03:50 +0200

> From: Drew Adams <drew.adams <at> oracle.com>
> CC: "52007 <at> debbugs.gnu.org" <52007 <at> debbugs.gnu.org>
> Date: Sun, 21 Nov 2021 17:45:53 +0000
> 
> > > That's not what it means to toggle `foo-mode'
> > > everywhere.  Doing that would flip the value that
> > > `foo-mode' (non-global mode) has in each buffer.
> > 
> > And it does.
> 
> It does not.  If `foo-mode' is on in buffer A, and
> the global mode is off, then toggling the global mode
> results in `foo-mode' being (still) on in buffer A.
> 
> Toggling `foo-mode' in all buffers (which is what
> the erroneous doc string said) would turn it on where
> it is off and off where it is on.  It would turn it
> off in buffer A.  It does not do so; it doesn't
> toggle `foo-mode' in each buffer; instead, it turns
> the mode on everywhere or off everywhere, depending
> on the value of `global-foo-mode'.

You are splitting hair.  The doc string describes what happens when
the mode is off everywhere.

> But as you've acknowledged, the bug exists in 27.2,
> the latest Emacs release.

I didn't try this in Emacs 27, so I didn't acknowledge that.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: "52007 <at> debbugs.gnu.org" <52007 <at> debbugs.gnu.org>
Subject: RE: [External] : Re: bug#52007: 26.3; Doc of
 `define-globalized-minor-mode' and global(ized) minor modes
Date: Sun, 21 Nov 2021 18:25:23 +0000

> > > > That's not what it means to toggle `foo-mode'
> > > > everywhere.  Doing that would flip the value that
> > > > `foo-mode' (non-global mode) has in each buffer.
> > >
> > > And it does.
> >
> > It does not.  If `foo-mode' is on in buffer A, and
> > the global mode is off, then toggling the global mode
> > results in `foo-mode' being (still) on in buffer A.
> >
> > Toggling `foo-mode' in all buffers (which is what
> > the erroneous doc string said) would turn it on where
> > it is off and off where it is on.  It would turn it
> > off in buffer A.  It does not do so; it doesn't
> > toggle `foo-mode' in each buffer; instead, it turns
> > the mode on everywhere or off everywhere, depending
> > on the value of `global-foo-mode'.
> 
> You are splitting hair.  The doc string describes what happens when
> the mode is off everywhere.

Not at all splitting hairs.  The doc string said
that the NON-global mode gets toggled in each
buffer, and it does not - not at all.

> > But as you've acknowledged, the bug exists in 27.2,
> > the latest Emacs release.
> 
> I didn't try this in Emacs 27, so I didn't acknowledge that.

I thought you said that the erroneous doc I reported
is getting fixed for Emacs 28.

Previous Next

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