bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's a minor mode

bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's a minor mode

[Drew Adams]

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)

bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's a minor mode

[Stefan Kangas]

Drew Adams <drew.adams@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

bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's a minor mode

[Eli Zaretskii]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Sun, 2 Aug 2020 03:47:14 -0700
> 
> Drew Adams <drew.adams@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.

bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's a minor mode

[Drew Adams]

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

bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's a minor mode

[Drew Adams]

> > > 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.)]

bug#29497: 26.0.90; doc strings of minor modes

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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