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

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

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

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Sat, 5 Aug 2006 14:37:25 -0700
> 
> 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").

I think ``"View" in mode line'' is better.

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

[Richard Stallman]

I implemented most of your suggestions, but rather than using columns,
I just filled the paragraph.

    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.

I pretty much agree, but I am not going to try to implement that.

    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),

That would be a big change.  The description of the command is what
we have available.

    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.

It is a reasonable idea, but too big a change to be considered for now.

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

[Drew Adams]

    I implemented most of your suggestions, but rather than using columns,
    I just filled the paragraph.

Thx.

        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.

    I pretty much agree, but I am not going to try to implement that.

It's an "inconvenience" bug that could perhaps be fixed after the release. I
didn't mean that this should be changed before the release.

        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.

    It is a reasonable idea, but too big a change to be considered for now.

Yes, I didn't mean to suggest that this should be changed before the
release. If implemented, this new feature would let us clean up the `C-h m'
treatment of minor modes, by extracting only the mode descriptions, not the
command descriptions, for `C-h m'. It might also encourage better minor-mode
descriptions.

`C-h m' is an important means of communication, in many cases, of
information that is not available elsewhere (unless there is an info manual
for the mode). Some modes are well described; some others are not. Cleaning
up the minor-mode part of `C-h m' would be one general improvement that
could be made. Improving individual major-mode doc strings would be another
step in the right direction.