Subject: bug#2473: usability issues on emacs's describe-mode

From: Richard M Stallman <[email-masked]>
Date: Fri, 27 Feb 2009 05:10:49 -0500

Most of the minor modes, filled with emacs-specific technicalities  
    and terminologies, are not something emacs users need to know daily.  
    When user calls describe-mode, most of the time she really want to  
    know what functionality and shortcuts the major mode provides. But  
    these minor modes often fills more than 60% of the page.

    To me, it is really a pain to read (a emacs user for 10 years), and i  
    have learned the habit not even seeing them. I imagine it is very  
    confusing to new emacs users.

YOU enabled a lot of those minor modes.
Here's what I get in emacs -Q:

    Enabled minor modes: Auto-Composition Auto-Compression Auto-Encryption
    File-Name-Shadow Font-Lock Global-Auto-Composition Global-Font-Lock
    Gpm-Mouse Line-Number Menu-Bar Tool-Bar Tooltip Transient-Mark

    (Information about these minor modes follows the major mode info.)
 
I don't think that list is going to make it hard for anyone to keep
reading.  You're making a mountain out of a molehill.

    Imagine, it has to annoy users about discussion such as Blink-Cursor,  
    Tooltip, Menu-Bar, Mouse-Wheel, Transient-Mark, Delete-Selection,  
    Font-Lock, Line-Number. Each of these is at least one paragraph long,  

These are at the END.  When the user sees them, she has already read
the info on the major mode, and she knows it.  She will only try to read
about the minor modes if she is curious about them.

We list the minor mode info here as well as the major mode info,
because otherwise we would need a separate command to give info about
them, and that would be burdensome in another way.  The way we present
it is the best possible compromise between the various goals.  It
gives the minor mode info in brief form at the front, but puts most of
it at the end, out of the way.

I do see two ways to improve this:

* Most minor mode doc strings include a standard explanation of what
the argument means.  We could include one copy of that standard
explanation at the front of the list of minor mode doc strings, and
then delete it from each of the individual doc strings, leaving just
the explanation of what the mode means.

* Some of these modes which are now enabled by default could perhaps
be eliminated, leaving them only as options, or perhaps removing them
entirely.  That would shorten the list of enabled minor modes and make
what remains more interesting.

For instance, do we need to have Auto Compression mode as a minor
mode?  If you want to examine one compressed file without
uncompressing it, it is easier to use find-file-literally.  I think it
is only for debugging that one would ever disable use Auto Compression
mode.  For that purpose, a No Auto Compression mode would be just as
good, or perhaps a No File Handlers mode.

Here are other default-on minor modes we should perhaps eliminate as
modes:

Auto-Composition Auto-Encryption File-Name-Shadow
Global-Auto-Composition Gpm-Mouse Line-Number Tooltip