GNU bug report logs - #20462
25.0.50; A minor mode's doc string should say it is [local/global] a minor mode

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 20462 in the body.
You can then email your comments to 20462 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
Subject: 25.0.50; A minor mode's doc string should say it is [local/global] a
 minor mode
Date: Wed, 29 Apr 2015 10:29:46 -0700 (PDT)

A minor mode created conventionally, i.e., using `define-minor-mode' or
`define-globalized-minor-mode', should automatically have its doc string
say explicitly that it is a minor mode and whether it is local or
global.

That helps users know what to expect, because all such minor modes have
some things in common, which are well documented.

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2015-04-05 on LEG570
Bzr revision: 16eec6fc55dcc05d1d819f18998e84a9580b2521
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=i686-pc-mingw32 --enable-checking=yes,glyphs'

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

From: Glenn Morris <rgm <at> gnu.org>
To: 20462 <at> debbugs.gnu.org
Subject: Re: bug#20462: 25.0.50;
 A minor mode's doc string should say it is [local/global] a minor mode
Date: Thu, 30 Apr 2015 03:12:49 -0400

(define-globalized-minor-mode foo auto-fill-mode 'ignore)

C-h foo

Toggle Auto-Fill mode in all buffers.

1) It's a minor mode (you can't toggle a major mode, nor sensibly apply
it to all buffers).
2) It's global ("all buffers").



(define-minor-mode blah nil)

C-f blah

Toggle Blah mode on or off.

1) It's a minor mode (you can't toggle a major mode)
2) Since it does not say it affects all buffers, don't assume it does.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Glenn Morris <rgm <at> gnu.org>, 20462 <at> debbugs.gnu.org
Subject: RE: bug#20462: 25.0.50; A minor mode's doc string should say it is
 [local/global] a minor mode
Date: Thu, 30 Apr 2015 06:47:58 -0700 (PDT)

> (define-globalized-minor-mode foo auto-fill-mode 'ignore)
> C-h foo
> Toggle Auto-Fill mode in all buffers.
> 
> 1) It's a minor mode (you can't toggle a major mode, nor sensibly
> apply it to all buffers).
> 2) It's global ("all buffers").
> (define-minor-mode blah nil)
> C-f blah
> Toggle Blah mode on or off.
> 1) It's a minor mode (you can't toggle a major mode)
> 2) Since it does not say it affects all buffers, don't assume it
> does.

Irrelevant to this bug report.  A command that toggles something,
including toggling a mode, is not necessarily a minor-mode command. 

See, for example, the misnamed `use-hard-newlines' command of
bug #20464.  It happens to be a minor-mode command.  But with
that name it might just as well not have been.  And there is
no way to tell from its doc string that it has anything to do
with a minor mode.  `define-globalized-minor-mode' and
`define-minor-mode' should explicitly add something to the
doc string to make clear that the command is not just some
command that toggles.  They should explicitly mention "minor mode".

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Glenn Morris <rgm <at> gnu.org>, 20462 <at> debbugs.gnu.org
Subject: RE: bug#20462: 25.0.50; A minor mode's doc string should say it is
 [local/global] a minor mode
Date: Thu, 30 Apr 2015 06:55:56 -0700 (PDT)

> See, for example, the misnamed `use-hard-newlines' command of
> bug #20464.

I meant bug #20461, which is about the name.

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

From: Artur Malabarba <bruce.connor.am <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Glenn Morris <rgm <at> gnu.org>, 20462 <at> debbugs.gnu.org
Subject: Re: bug#20462: 25.0.50; A minor mode's doc string should say it is
 [local/global] a minor mode
Date: Thu, 30 Apr 2015 16:36:04 +0100

2015-04-30 14:47 GMT+01:00 Drew Adams

>> (define-globalized-minor-mode foo auto-fill-mode 'ignore)
>> C-h foo
>> Toggle Auto-Fill mode in all buffers.
>>
>> 1) It's a minor mode (you can't toggle a major mode, nor sensibly
>> apply it to all buffers).
>> 2) It's global ("all buffers").
>> (define-minor-mode blah nil)
>> C-f blah
>> Toggle Blah mode on or off.
>> 1) It's a minor mode (you can't toggle a major mode)
>> 2) Since it does not say it affects all buffers, don't assume it
>> does.
>
> Irrelevant to this bug report.  A command that toggles something,
> including toggling a mode, is not necessarily a minor-mode command.

I agree with Drew here. The fact that this information can be inferred
(deciphered, perhaps) from the docstring doesn't mean that it
shouldn't be included explicitly. Even more so where it comes minor
modes, which are commands that even the most basic users will interact
with (and probably read).

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 20462 <at> debbugs.gnu.org
Subject: Re: bug#20462: 25.0.50;
 A minor mode's doc string should say it is [local/global] a minor mode
Date: Sat, 30 Apr 2016 21:03:32 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> A minor mode created conventionally, i.e., using `define-minor-mode' or
> `define-globalized-minor-mode', should automatically have its doc string
> say explicitly that it is a minor mode and whether it is local or
> global.
>
> That helps users know what to expect, because all such minor modes have
> some things in common, which are well documented.

Yeah, I kinda think that `define-minor-mode' should include the toggle
verbiage by default at the start of all doc strings, even if there is a
doc string given.  That would mean going through all the usages in the
tree and remove the leading incantations, but that's no big deal.

We could have a keyword :no-introduction t for the few modes that really
don't want the standard verbiage at the start.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Drew Adams <drew.adams <at> oracle.com>
To: 20462 <at> debbugs.gnu.org
Subject: RE: bug#20462: 25.0.50; A minor mode's doc string should say it is
 [local/global] a minor mode
Date: Mon, 2 Jan 2017 13:59:55 -0800 (PST)

In addition, I think it would be good if the doc for the mode
either mentioned whether the mode is currently on or (at least)
mentioned the associated variable, letting users know that the
value of that variable will tell them whether it is currently
on or off.  (They might also need to be told that they need to
examine the variable value in the appropriate buffer.  Or else
clicking the variable link in the doc for the function should
evaluate it in the proper buffer (same buffer that the function
doc was invoked from).

Previous Next

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