unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#52007: 26.3; Doc of `define-globalized-minor-mode' and global(ized) minor modes
@ 2021-11-20 22:44 Drew Adams
  2021-11-20 23:17 ` Drew Adams
  2021-11-21  6:41 ` Eli Zaretskii
  0 siblings, 2 replies; 9+ messages in thread
From: Drew Adams @ 2021-11-20 22:44 UTC (permalink / raw)
  To: 52007

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






^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#52007: 26.3; Doc of `define-globalized-minor-mode' and global(ized) minor modes
  2021-11-20 22:44 bug#52007: 26.3; Doc of `define-globalized-minor-mode' and global(ized) minor modes Drew Adams
@ 2021-11-20 23:17 ` Drew Adams
  2021-11-21  6:42   ` Eli Zaretskii
  2021-11-21  6:41 ` Eli Zaretskii
  1 sibling, 1 reply; 9+ messages in thread
From: Drew Adams @ 2021-11-20 23:17 UTC (permalink / raw)
  To: Drew Adams, 52007@debbugs.gnu.org

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.





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#52007: 26.3; Doc of `define-globalized-minor-mode' and global(ized) minor modes
  2021-11-20 22:44 bug#52007: 26.3; Doc of `define-globalized-minor-mode' and global(ized) minor modes Drew Adams
  2021-11-20 23:17 ` Drew Adams
@ 2021-11-21  6:41 ` Eli Zaretskii
  1 sibling, 0 replies; 9+ messages in thread
From: Eli Zaretskii @ 2021-11-21  6:41 UTC (permalink / raw)
  To: Drew Adams; +Cc: 52007-done

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#52007: 26.3; Doc of `define-globalized-minor-mode' and global(ized) minor modes
  2021-11-20 23:17 ` Drew Adams
@ 2021-11-21  6:42   ` Eli Zaretskii
  2021-11-21 17:22     ` bug#52007: [External] : " Drew Adams
  0 siblings, 1 reply; 9+ messages in thread
From: Eli Zaretskii @ 2021-11-21  6:42 UTC (permalink / raw)
  To: Drew Adams; +Cc: 52007

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#52007: [External] : Re: bug#52007: 26.3; Doc of `define-globalized-minor-mode' and global(ized) minor modes
  2021-11-21  6:42   ` Eli Zaretskii
@ 2021-11-21 17:22     ` Drew Adams
  2021-11-21 17:28       ` Eli Zaretskii
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2021-11-21 17:22 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 52007@debbugs.gnu.org

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#52007: [External] : Re: bug#52007: 26.3; Doc of `define-globalized-minor-mode' and global(ized) minor modes
  2021-11-21 17:22     ` bug#52007: [External] : " Drew Adams
@ 2021-11-21 17:28       ` Eli Zaretskii
  2021-11-21 17:45         ` Drew Adams
  0 siblings, 1 reply; 9+ messages in thread
From: Eli Zaretskii @ 2021-11-21 17:28 UTC (permalink / raw)
  To: Drew Adams; +Cc: 52007

> From: Drew Adams <drew.adams@oracle.com>
> CC: "52007@debbugs.gnu.org" <52007@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.





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#52007: [External] : Re: bug#52007: 26.3; Doc of `define-globalized-minor-mode' and global(ized) minor modes
  2021-11-21 17:28       ` Eli Zaretskii
@ 2021-11-21 17:45         ` Drew Adams
  2021-11-21 18:03           ` Eli Zaretskii
  0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2021-11-21 17:45 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 52007@debbugs.gnu.org

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#52007: [External] : Re: bug#52007: 26.3; Doc of `define-globalized-minor-mode' and global(ized) minor modes
  2021-11-21 17:45         ` Drew Adams
@ 2021-11-21 18:03           ` Eli Zaretskii
  2021-11-21 18:25             ` Drew Adams
  0 siblings, 1 reply; 9+ messages in thread
From: Eli Zaretskii @ 2021-11-21 18:03 UTC (permalink / raw)
  To: Drew Adams; +Cc: 52007

> From: Drew Adams <drew.adams@oracle.com>
> CC: "52007@debbugs.gnu.org" <52007@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.





^ permalink raw reply	[flat|nested] 9+ messages in thread

* bug#52007: [External] : Re: bug#52007: 26.3; Doc of `define-globalized-minor-mode' and global(ized) minor modes
  2021-11-21 18:03           ` Eli Zaretskii
@ 2021-11-21 18:25             ` Drew Adams
  0 siblings, 0 replies; 9+ messages in thread
From: Drew Adams @ 2021-11-21 18:25 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: 52007@debbugs.gnu.org

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





^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2021-11-21 18:25 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-11-20 22:44 bug#52007: 26.3; Doc of `define-globalized-minor-mode' and global(ized) minor modes Drew Adams
2021-11-20 23:17 ` Drew Adams
2021-11-21  6:42   ` Eli Zaretskii
2021-11-21 17:22     ` bug#52007: [External] : " Drew Adams
2021-11-21 17:28       ` Eli Zaretskii
2021-11-21 17:45         ` Drew Adams
2021-11-21 18:03           ` Eli Zaretskii
2021-11-21 18:25             ` Drew Adams
2021-11-21  6:41 ` Eli Zaretskii

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).