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

From: Drew Adams <[email-masked]>
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''