GNU bug report logs - #41884
27.0.91; `C-h f whitespace-mode' doesn't say that it's 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 41884 in the body.
You can then email your comments to 41884 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: 27.0.91; `C-h f whitespace-mode' doesn't say that it's a minor mode
Date: Mon, 15 Jun 2020 15:36:10 -0700 (PDT)

Subject line says it all.  The doc string for a minor mode should tell
you it's a minor mode.


In GNU Emacs 27.0.91 (build 1, x86_64-w64-mingw32)
 of 2020-04-20 built on CIRROCUMULUS
Repository revision: c36c5a3dedbb2e0349be1b6c3b7567ea7b594f1c
Repository branch: HEAD
Windowing system distributor 'Microsoft Corp.', version 10.0.18362
System Description: Microsoft Windows 10 Pro (v10.0.1903.18362.836)

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

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>, 41884 <at> debbugs.gnu.org
Subject: Re: bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's
 a minor mode
Date: Sun, 2 Aug 2020 03:47:14 -0700

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

> Subject line says it all.  The doc string for a minor mode should tell
> you it's a minor mode.

Should all minor modes say this?  Because there are more examples of
modes that don't, such as:
- display-line-numbers-mode
- whitespace-newline-mode

This is just from taking a quick look.

Best regards,
Stefan Kangas

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefankangas <at> gmail.com>
Cc: 41884 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#41884: 27.0.91;
 `C-h f whitespace-mode' doesn't say that it's a minor mode
Date: Sun, 02 Aug 2020 17:25:26 +0300

> From: Stefan Kangas <stefankangas <at> gmail.com>
> Date: Sun, 2 Aug 2020 03:47:14 -0700
> 
> Drew Adams <drew.adams <at> oracle.com> writes:
> 
> > Subject line says it all.  The doc string for a minor mode should tell
> > you it's a minor mode.
> 
> Should all minor modes say this?

No, they don't.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefankangas <at> gmail.com>, 41884 <at> debbugs.gnu.org
Subject: RE: bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's
 a minor mode
Date: Sun, 2 Aug 2020 09:27:41 -0700 (PDT)

> > The doc string for a minor mode should tell
> > you it's a minor mode.
> 
> Should all minor modes say this?  Because there are more examples of
> modes that don't, such as:
> - display-line-numbers-mode
> - whitespace-newline-mode
> 
> This is just from taking a quick look.

Yes, IMO they should.  Otherwise, how will
users know?  (OK, there are ways...)

Knowing a command is a minor mode is very
important to understanding its use.  It's
could even be argued that it's the most
important thing to know about it.
____

More generally, I think a failing of some
minor-mode doc strings is that they don't
tell you the basics of what the doc string
of `define-minor-mode' tells you, e.g. how
to turn the mode on/off, both interactively
and from Lisp.

This related problem has been taken care of
here and there over the years, bit by bit,
from bug reports etc.  But I think the
problem is still present here and there.

Anyway, this bug report is only about
`whitespace-mode'.  If someone wants to
fix its problem along with that of other
minor-mode commands, please do.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Stefan Kangas <stefankangas <at> gmail.com>
Cc: 41884 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: RE: bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's
 a minor mode
Date: Sun, 2 Aug 2020 09:27:56 -0700 (PDT)

> > > The doc string for a minor mode should tell
> > > you it's a minor mode.
> >
> > Should all minor modes say this?
> 
> No, they don't.

That wasn't Stefan's question.  Should they?
I think they should.

Typically it takes only adding the words "minor
mode".  In the case of `whitespace-mode' it takes
only adding the word "minor":

 Toggle whitespace visualization (Whitespace minor mode).

I can't imagine why we _wouldn't_ want to tell
users this in the doc string.
____

[And, for the related problem that crops up wrt
minor-mode command doc strings - of not always
documenting well how to turn the mode on/off:
if someone decides to opt for a simple one-size
fits all fix, then that could be to just provide
a link to the doc about minor modes in each
minor-mode doc string.

IOW, once every minor-mode doc string says that
it's about a minor mode, a simple link to the doc
that tells you about minor modes would take care
of lacunae such as the doc string neglecting to
tell you clearly how to turn it on/off.

(It's still better to give that info directly in
the doc string, IMO, but such a link would make
sure to cover any such omission.)]

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 41884 <at> debbugs.gnu.org, 29497 <at> debbugs.gnu.org
Subject: Re: bug#29497: 26.0.90; doc strings of minor modes
Date: Wed, 30 Jun 2021 15:31:47 +0200

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

> Subject line says it all.  The doc string for a minor mode should tell
> you it's a minor mode.

I've now added this to the Emacs 28 minor mode doc strings.

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

Previous Next

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