1) `C-h m' minor mode info is too noisy 2) other suggestions about minor-mode help

[Drew Adams]

I see this kind of thing at the top of the buffer when I do `C-h m':

 Summary of minor modes:
  Auto-Compression minor mode (no indicator):
  Blink-Cursor minor mode (no indicator):
  Column-Number minor mode (no indicator):
  Delete-Selection minor mode (no indicator):
  Display-Time minor mode (no indicator):
  Encoded-Kbd minor mode (no indicator):
  File-Name-Shadow minor mode (no indicator):
  Font-Lock minor mode (no indicator):
  Global-Font-Lock minor mode (no indicator):
  Icicle minor mode (indicator Icy):
  Icomplete minor mode (no indicator):
  Line-Number minor mode (no indicator):
  Menu-Bar minor mode (no indicator):
  Minibuffer-Indicate-Depth minor mode (no indicator):
  Mouse-Wheel minor mode (no indicator):
  Recentf minor mode (no indicator):
  Show-Paren minor mode (no indicator):
  Tool-Bar-Pop-Up minor mode (no indicator):
  Transient-Mark minor mode (no indicator):
  Unify-8859-On-Encoding minor mode (no indicator):
  Utf-Translate-Cjk minor mode (no indicator):
  View minor mode (indicator View):

 (Full information about these minor modes
 follows the description of the major mode.)

Why not make this a little less noisy, by doing these things:

1. Get rid of "(no indicator)". It's enough to say what the indicator is if
there is one. Don't bother to say "indicator" at all, just put the indicator
name in parens, in quotes: ("View").

[BTW: sometimes this is called "indicator" in the doc (e.g. here), sometimes
it is called "lighter" (which means nothing, to me).]

3. Get rid of ":" - that's just a typo here (a vestige of its origin).

4. Get rid of "minor mode" - we've already said that these are minor modes.

5. Remove the parens around "Full information...." - no need for them. And
shorten that sentence to one line.

The result would be this, which is much more readable, IMO:

 Summary of minor modes:
  Auto-Compression
  Blink-Cursor
  Column-Number
  Delete-Selection
  Display-Time
  Encoded-Kbd
  File-Name-Shadow
  Font-Lock
  Global-Font-Lock
  Icicle ("Icy")
  Icomplete
  Line-Number
  Menu-Bar
  Minibuffer-Indicate-Depth
  Mouse-Wheel
  Recentf
  Show-Paren
  Tool-Bar-Pop-Up
  Transient-Mark
  Unify-8859-On-Encoding
  Utf-Translate-Cjk
  View minor mode ("View")

 More information follows the description of the major mode.

It might be even better to list the minor modes in columns, to save space:

 Summary of minor modes:
  Auto-Compression        Blink-Cursor            Column-Number
  Delete-Selection        Display-Time            Encoded-Kbd
  File-Name-Shadow        Font-Lock               Global-Font-Lock
  Icicle ("Icy")          Icomplete               Line-Number
  Menu-Bar                Minibuffer-Indicate-Depth
  Mouse-Wheel             Recentf                 Show-Paren
  Tool-Bar-Pop-Up         Transient-Mark          Unify-8859-On-Encoding
  Utf-Translate-Cjk       View minor mode ("View")

 More information follows the description of the major mode.

WDOT? About 1/3 the number of lines, and more readable, IMO.

[BTW, why are there now so many minor modes that are used without user
request for them? I'm thinking, for instance, of things like Encoded-Kbd,
Unify-8859-On-Encoding and Utf-Translate-Cjk? I don't really object, but it
can tend to make you lose the forest for the trees when you look through a
buffer like `C-h m'.]


Some other suggestions about minor-mode help in `C-h m':

1. If you click a minor-mode name in the list, you go to the minor-mode
description, but clicking [back] then does not take you back to the link you
clicked - it takes you to a previous *Help* screen. This seems like a bug.
If [back] can't be made to DTRT, then each minor-mode description should
have a [back] (or [top]) link.

2. Each of the minor-mode descriptions is actually a description of the
command that toggles the mode, not the mode itself, but nothing indicates
this, and the command name is not even mentioned! Each description thus
starts with several lines about toggling, which is quite repetitive
(obfuscatory, in fact). It would be better to have just a description of the
mode itself (not the command), and simply say, once and for all, that a
minor mode command is a toggle (or skip saying that here altogether).

Example (good):

 Icomplete minor mode:
 Incremental minibuffer completion help.

Versus what we have now (bad):

 Icomplete minor mode (no indicator):
 Toggle incremental minibuffer completion for this Emacs session.
 With a numeric argument, turn Icomplete mode on iff ARG is positive.

To change the command doc strings into useful mode descriptions would
require a bit of massaging, but it should be possible to do that.

Also, we could add a guideline for writing such doc strings (for
`define-minor-mode'), to make this easier (and produce better results) in
the future. Part of the info about toggling could be semi-automated by
`define-minor-mode', provided the mode is conventional. The current doc for
`define-minor-mode' provides no guidelines for writing the doc string
(beyond an example that is not very exemplary in this regard). I'd propose a
guideline such as this:

 "A short description of the turned-on state of the mode:
 what is true or what happens when the mode is on."

If there is nothing unconventional about the toggling, then the toggling
info would be provided automatically by `define-minor-mode'. If there is
something unconventional, then that info could be included in a second,
optional doc-string arg. When that optional arg is present,
`define-minor-mode' would not automatically add the (conventional) toggling
info.

If it's too hard to add an additional optional arg now, then the flag could
be an asterisk as the first character of the doc string: if present, then
`define-minor-mode' would assume that you are providing the info about
toggling the mode in the doc string; if absent, then `define-minor-mode'
would add that info automatically.

This would help `C-h m' produce readable descriptions of the modes,
descriptions that do not include info on how to toggle them, but asking for
help on the command would still provide the necessary toggling info (as well
as the info on what the mode is/does).