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

From: [email-masked] (GNU bug Tracking System)
Date: Sun, 21 Nov 2021 06:42:01 +0000

Your bug report

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

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
52007: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=52007
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#52007: 26.3; Doc of `define-globalized-minor-mode' and global(ized) minor modes
From: Eli Zaretskii <[email-masked]>
To: Drew Adams <[email-masked]>
Cc: [email-masked]
Date: Sun, 21 Nov 2021 08:41:13 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

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

Subject: 26.3; Doc of `define-globalized-minor-mode' and global(ized) minor modes
From: Drew Adams <[email-masked]>
To: "[email-masked]" <[email-masked]>
Date: Sat, 20 Nov 2021 22:44:23 +0000
List-Id: <debbugs-submit.debbugs.gnu.org>

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