unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's a minor mode
@ 2020-06-15 22:36 Drew Adams
  2020-08-02 10:47 ` Stefan Kangas
  2021-06-30 13:31 ` bug#29497: 26.0.90; doc strings of minor modes Lars Ingebrigtsen
  0 siblings, 2 replies; 6+ messages in thread
From: Drew Adams @ 2020-06-15 22:36 UTC (permalink / raw)
  To: 41884

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)





^ permalink raw reply	[flat|nested] 6+ messages in thread

* bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's a minor mode
  2020-06-15 22:36 bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's a minor mode Drew Adams
@ 2020-08-02 10:47 ` Stefan Kangas
  2020-08-02 14:25   ` Eli Zaretskii
  2020-08-02 16:27   ` Drew Adams
  2021-06-30 13:31 ` bug#29497: 26.0.90; doc strings of minor modes Lars Ingebrigtsen
  1 sibling, 2 replies; 6+ messages in thread
From: Stefan Kangas @ 2020-08-02 10:47 UTC (permalink / raw)
  To: Drew Adams, 41884

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





^ permalink raw reply	[flat|nested] 6+ messages in thread

* bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's a minor mode
  2020-08-02 10:47 ` Stefan Kangas
@ 2020-08-02 14:25   ` Eli Zaretskii
  2020-08-02 16:27   ` Drew Adams
  1 sibling, 0 replies; 6+ messages in thread
From: Eli Zaretskii @ 2020-08-02 14:25 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: 41884

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





^ permalink raw reply	[flat|nested] 6+ messages in thread

* bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's a minor mode
  2020-08-02 10:47 ` Stefan Kangas
  2020-08-02 14:25   ` Eli Zaretskii
@ 2020-08-02 16:27   ` Drew Adams
  1 sibling, 0 replies; 6+ messages in thread
From: Drew Adams @ 2020-08-02 16:27 UTC (permalink / raw)
  To: Stefan Kangas, 41884

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





^ permalink raw reply	[flat|nested] 6+ messages in thread

* bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's a minor mode
       [not found]   ` <<833655ceg9.fsf@gnu.org>
@ 2020-08-02 16:27     ` Drew Adams
  0 siblings, 0 replies; 6+ messages in thread
From: Drew Adams @ 2020-08-02 16:27 UTC (permalink / raw)
  To: Eli Zaretskii, Stefan Kangas; +Cc: 41884

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





^ permalink raw reply	[flat|nested] 6+ messages in thread

* bug#29497: 26.0.90; doc strings of minor modes
  2020-06-15 22:36 bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's a minor mode Drew Adams
  2020-08-02 10:47 ` Stefan Kangas
@ 2021-06-30 13:31 ` Lars Ingebrigtsen
  1 sibling, 0 replies; 6+ messages in thread
From: Lars Ingebrigtsen @ 2021-06-30 13:31 UTC (permalink / raw)
  To: Drew Adams; +Cc: 41884, 29497

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





^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2021-06-30 13:31 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-06-15 22:36 bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's a minor mode Drew Adams
2020-08-02 10:47 ` Stefan Kangas
2020-08-02 14:25   ` Eli Zaretskii
2020-08-02 16:27   ` Drew Adams
2021-06-30 13:31 ` bug#29497: 26.0.90; doc strings of minor modes Lars Ingebrigtsen
     [not found] <<2f814ee0-f472-43f6-878b-a9c9489d771e@default>
     [not found] ` <<CADwFkmm+bEojs03A76PoLPO08CQpTCfQZgErP2gYbXYumai1sw@mail.gmail.com>
     [not found]   ` <<833655ceg9.fsf@gnu.org>
2020-08-02 16:27     ` bug#41884: 27.0.91; `C-h f whitespace-mode' doesn't say that it's a minor mode Drew Adams

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).