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

From: Eli Zaretskii <[email-masked]>
Date: Fri, 27 Feb 2009 13:04:01 +0200

> From: Richard M Stallman <[email-masked]>
> Date: Fri, 27 Feb 2009 05:10:49 -0500
> Cc: [email-masked]
> 
> 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:

I see a 3rd way: make the buffer present an expandable list of modes,
starting with just 2 items: the current major modes and "minor modes",
e.g. similar to what we do in Speedbar, or maybe in Outline Mode
(under "Hide Sublevels").  In ASCII art:

  + Major Mode: RMAIL Mode
  + Minor Modes

Clicking on a plus near Major Mode would then expand to the text we
currently show for that major mode, for example:

  - Major Mode: RMAIL mode
	 Rmail Mode is used by M-x rmail for editing Rmail files.
	 All normal editing commands are turned off.
	 Instead, these commands are available:

	 .    Move point to front of this message.
	 /    Move point to bottom of this message.
	 SPC  Scroll to next screen of this message.
	 DEL  Scroll to previous screen of this message.
	 n    Move to Next non-deleted message.
	 p    Move to Previous non-deleted message.

  + Minor Modes

Clicking on "Minor Modes" would show only the list of modes with short
descriptions:

  - Minor Modes:
    + Auto-Compression -- automatic file compression and uncompression.
    + Blink-Cursor -- blink cursor in current window.
    + Desktop-Save -- save Emacs session on exit.
    + Display-Time -- display time, load average, and mail flag in modeline.
    + File-Name-Shadow -- shadow ignored part of file name in minibuffer.

etc., you get the picture.  (We could also have a tooltip on each line
showing more info for that mode.)  Clicking on any of the plus signs
near a minor mode would display the full documentation for that minor
mode, the one we show today unconditionally.

This way, the user will be able to expand only the modes she is
interested in.  Using the short description, the user will be able to
find out what is/are the modes she is interested in, if she doesn't
know that in advance.

For more functionality, we could add buttons and/or help-echo links to
go to the manual where the mode is fully described.

WDYT?