GNU bug report logs - #59600
28.1.90; Docstrings generated by `define-globalized-minor-mode' and `define-minor-mode' :global t are not same

Previous Next

To reply to this bug, email your comments to 59600 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

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

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: bug-gnu-emacs <at> gnu.org
Subject: 28.1.90; Docstrings generated by `define-globalized-minor-mode' and
 `define-minor-mode' :global t are not same
Date: Sat, 26 Nov 2022 06:21:13 +0000

Hi,

I noticed inconsistency between minor modes defined via
`define-globalized-minor-mode' and via `define-minor-mode' with :global
t keyword.

The former have the following in their docstring:

"Toggle %s in all buffers.\n"
"%s is enabled in all buffers where `%s' would do it."

However, no indication is given that globalized minor mode defined via
`define-minor-mode' :global t is global.

For example, `auto-save-visited-mode' is a global minor mode, but no
clear indication of this fact is given. It did cause confusion for some
users.

Expected: :global t clearly indicates that the mode is global.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Ihor Radchenko <yantar92 <at> posteo.net>,
 Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 59600 <at> debbugs.gnu.org
Subject: Re: bug#59600: 28.1.90;
 Docstrings generated by `define-globalized-minor-mode' and
 `define-minor-mode' :global t are not same
Date: Sat, 26 Nov 2022 10:15:36 +0200

> From: Ihor Radchenko <yantar92 <at> posteo.net>
> Date: Sat, 26 Nov 2022 06:21:13 +0000
> 
> I noticed inconsistency between minor modes defined via
> `define-globalized-minor-mode' and via `define-minor-mode' with :global
> t keyword.
> 
> The former have the following in their docstring:
> 
> "Toggle %s in all buffers.\n"
> "%s is enabled in all buffers where `%s' would do it."
> 
> However, no indication is given that globalized minor mode defined via
> `define-minor-mode' :global t is global.
> 
> For example, `auto-save-visited-mode' is a global minor mode, but no
> clear indication of this fact is given. It did cause confusion for some
> users.
> 
> Expected: :global t clearly indicates that the mode is global.

Adding Stefan to the discussion.

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Ihor Radchenko <yantar92 <at> posteo.net>, 59600 <at> debbugs.gnu.org
Subject: Re: bug#59600: 28.1.90; Docstrings generated by
 `define-globalized-minor-mode' and `define-minor-mode' :global t are not
 same
Date: Sat, 26 Nov 2022 12:38:33 -0500

>> The former have the following in their docstring:
>> 
>> "Toggle %s in all buffers.\n"
>> "%s is enabled in all buffers where `%s' would do it."
>> 
>> However, no indication is given that globalized minor mode defined via
>> `define-minor-mode' :global t is global.

[ Nitpick: "define-minor-mode :global t" does not (usually) define
  a "globalized mode" but rather it defines a "global mode".  ]

>> For example, `auto-save-visited-mode' is a global minor mode, but no
>> clear indication of this fact is given. It did cause confusion for some
>> users.
>> 
>> Expected: :global t clearly indicates that the mode is global.
>
> Adding Stefan to the discussion.

Not much to say, but I agree it makes sense for the docstring to state
the scope of the mode (global, buffer-local, younameit).


        Stefan

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: yantar92 <at> posteo.net, 59600 <at> debbugs.gnu.org
Subject: Re: bug#59600: 28.1.90; Docstrings generated by
 `define-globalized-minor-mode' and `define-minor-mode' :global t are not
 same
Date: Sat, 26 Nov 2022 19:46:34 +0200

> From: Stefan Monnier <monnier <at> iro.umontreal.ca>
> Cc: Ihor Radchenko <yantar92 <at> posteo.net>,  59600 <at> debbugs.gnu.org
> Date: Sat, 26 Nov 2022 12:38:33 -0500
> 
> [ Nitpick: "define-minor-mode :global t" does not (usually) define
>   a "globalized mode" but rather it defines a "global mode".  ]
> 
> >> For example, `auto-save-visited-mode' is a global minor mode, but no
> >> clear indication of this fact is given. It did cause confusion for some
> >> users.
> >> 
> >> Expected: :global t clearly indicates that the mode is global.
> >
> > Adding Stefan to the discussion.
> 
> Not much to say, but I agree it makes sense for the docstring to state
> the scope of the mode (global, buffer-local, younameit).

Patches to the macro that defines the modes are welcome.

Previous Next

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