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

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

[xah lee]

hi guys,

Some problem i think on emacs describe-mode.

   http://xahlee.org/emacs/modernization_mode_doc.html

Here's a plain text version. Following the text is some proposed code  
solution (beta) that fixes 2 of the issues.

--------------------------

Usability Problems Of Emacs's Mode Documentation

Xah Lee, 2009-02-06

This page details some usability problems of Emacs's inline  
documentation for its major-mode.

Emacs has a command describe-mode (Ctrl+h m) that shows the inline  
doc for the current mode. For example, if you are coding in  
javascript, html, perl, or python, you can type “Ctrl+h m” to  
quickly see a summarization of what functionalities you have while  
coding in that lang, and what are the keyboard shortcuts.

This is really a wonderful feature, but it is a shame that it has  
some major usability problem, almost making this feature not usable.  
The following gives some details.

For example, when in w3m mode, which is a mode that allows you to  
browse the web pages, i type “Ctrl+h m” to read the online doc  
about the mode's features. The result page starts like this:

     Enabled minor modes: Abbrev Auto-Compression Blink-Cursor
     Command-Frequency Command-Frequency-Autosave Delete-Selection
     Desktop-Save Encoded-Kbd File-Name-Shadow Font-Lock Global-Font- 
Lock
     Line-Number Menu-Bar Mouse-Wheel Recentf Shell-Dirtrack Show-Paren
     Tooltip Transient-Mark Unify-8859-On-Encoding Utf-Translate-Cjk

     (Information about these minor modes follows the major mode info.)

It began by listing “minor-modes”. (What Emacs calls “minor  
modes”, is similar in concept to modern app's preference settings  
and add-ons features.)

Here's a excerpt of the minor mode doc that comes after the major  
mode doc:

     ^L
     Abbrev minor mode (indicator Abbrev):
     Toggle Abbrev mode in the current buffer.
     With optional argument ARG, turn abbrev mode on if ARG is
     positive, otherwise turn it off.  In Abbrev mode, inserting an
     abbreviation causes it to expand and be replaced by its expansion.
     ^L
     Auto-Compression minor mode (no indicator):
     Toggle automatic file compression and uncompression.
     With prefix argument ARG, turn auto compression on if positive,  
else off.
     Return the new status of auto compression (non-nil means on).
     ^L
     Blink-Cursor minor mode (no indicator):
     Toggle blinking cursor mode.
     With a numeric argument, turn blinking cursor mode on if ARG is  
positive,
     otherwise turn it off.  When blinking cursor mode is enabled, the
     cursor of the selected window blinks.

     Note that this command is effective only when Emacs
     displays through a window system, because then Emacs does its own
     cursor display.  On a text-only terminal, this is not implemented.
     ^L
     Cua minor mode (no indicator):
     Toggle CUA key-binding mode.
     When enabled, using shifted movement keys will activate the
     region (and highlight the region using `transient-mark-mode'),
     and typed text replaces the active selection.

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.

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,  
and some are emacs's non-intuitive and weired tech jargons. For  
example, the standard feature of having selected text highlighted, is  
in emacs called transient-mark-mode. The standard feature of typing  
overriding selected text, is in emacs tech jargon called delete- 
selection-mode. The standard feature of copy/cut/paste keys, is in  
emacs called cua-mode. Syntax highlighting is called font-lock-mode.

Does user really need to know, that he has Blinking Cursor on? And a  
user needs to be told of the fact he has mouse wheel support on? And  
menu bar, tooltip, syntax highlighting? Do users need explanation  
what these do too?

The emacs minor mode, also includes proper features such as: Show- 
Paren, Recentf, Desktop-Save, Abbrev, Yas/Minor ... etc. For example,  
show-paren-mode highlight matching parenthesis. “recentf-mode”  
lets user open recently opened files. “desktop-save-mode”  
preserves opened files when emacs restarts.

It is nice to be able to see what features are currently on, and what  
extra functionality it supports, but perhaps a separate command  
describe-minor-modes would be better.

Minor mode listing also include a bunch that shows some technical  
issues of emacs's current state that has little to do with daily use  
of emacs. For example, it shows Shell-Dirtrack, Auto-Compression,  
Encoded-Kbd, File-Name-Shadow, Unify-8859-On-Encoding, Utf-Translate- 
Cjk. I have used emacs daily for 10 years, half of the minor mode  
showing up in describe-mode i don't even know what exactly they are.

Also, the page litters “^L” char (ascii 12) through out. The  
“^L” is a page break marker. Such practice is a convention in the  
1980s. Almost no software today does this, and very few professional  
programers today understand what it is. This adds to the  
incomprehensibility.

I think the major usability problem with describe-mode is the listing  
of minor modes. Though, the major mode's inline doc could also use  
some improvement. Here's a excerpt of the inline doc for w3m:

     w3m mode:
     Major mode for browsing web.

     RET     Display the page pointed to by the link under point.   
You may use
             the prefix arg `2' or `C-u C-u' to make a new session.

             If w3m-use-form is t, `RET' and `<mouse-2>' enable you  
to enter forms.
             You may use the prefix arg `2' or `C-u C-u' to make a  
new session.

     <S-kp-enter>
             Display the page of the link in a new session.
             If the region is active, visit all the links within the  
region.

     <S-mouse-2>
             Display the page of the link in a new session by mouse.

     C-c C-c  Submit the form at point.

     R        Reload the current page.
     r        Redisplay the current page.
     C t      Redisplay the page, specifying a content type.
     C c      Redisplay the current page, specifying a charset.
     C C      Redisplay the current page and reset the user-specified  
charset and
              content type.

The notation for keyboard shortcuts, such as “C-u C-u”, “RET”,  
are hard to read. It becomes more confusing when there are shortcuts  
that doesn't use a modifier such as “C t”. The “<mouse-2>”  
and “S-kp-enter” are especially cryptic.
Suggestions

     * describe-mode should just show the inline doc for the major mode.
     * Add a link to the bottom that point to the full doc of the  
mode, if it exists. (the link may be to info doc, or call browse-url  
to open a html doc on local disk, or to a url online of the mode's  
doc website)
     * Get rid of convention of using ^L (ascii 12) for page break  
marker.
     * Add a link at the bottom, to a page that shows inline doc of  
minor modes.
     * Use curly quotes “” instead of the 1980's ascii kludge `'.

For detail about the key notation that adds up readability, see:  
Emacs's M-‹key› Notation vs Alt+‹key› Notation.

The use of backtick char ` and single quote char ' for “matching  
quotes” is a 1980's kludge. They also adds to the readability problem.

It would also be helpful, if the keys are rendered as buttons. Note  
that the button rendering is used in the help files in MS Windows and  
Mac OS X too. And in Wikipedia's articles related to keys, it is also  
used thru-out. e.g. Table of keyboard shortcuts.

Here's a sample output for comparison:

     w3m mode:
     Major mode for browsing web.

     Enter	Display the page pointed to by the link under point.
     You may use the prefix arg “2” or “Ctrl+u Ctrl+u” to make  
a new session.
     If w3m-use-form is t, “Enter” and “mouse middle button”  
enable you to enter forms.
     You may use the prefix arg “2” or “Ctrl+u Ctrl+u” to make  
a new session.
     Keypad Shift+Enter	Display the page of the link in a new session.
     If the region is active, visit all the links within the region.
     Shift+Mouse Middle Button	Display the page of the link in a new  
session by mouse.
     Ctrl+c Ctrl+c	Submit the form at point.
     R	Reload the current page.
     r	Redisplay the current page.
     C t	Redisplay the page, specifying a content type.
     C c	Redisplay the current page, specifying a charset.
     C C	Redisplay the current page and reset the user-specified  
charset and content type.


-------------------------

;; code by Kevin Rodgers. 2009-02-25
(defun describe-major-mode ()
   "Show inline doc for current major-mode."
   (interactive)
   (describe-function major-mode))

;; display page delimiter “^L” as a horizontal line. Code by  
Sébastien Vauban. 2009-02-25
(or standard-display-table
     (setq
      standard-display-table (make-display-table)))
(aset standard-display-table ?\f (vconcat "\n" (make-vector 60 ?-) "^L 
\n"))

;; Display the “^L” page break mark as a horizontal line
;; from http://www.emacswiki.org/emacs/OverlayControlL , 2009-02-25
;; code by Andre Riemann
(add-hook
  'after-change-major-mode-hook
  (lambda ()
    (font-lock-add-keywords nil
     `((,page-delimiter ;; variable with the regexp (usually "^\f" or  
"^^L")
         0
         (prog1 nil
           ;; don't display ^L
           (compose-region (match-beginning 0) (match-end 0) "")
           ;; make an overlay (like in hl-line)
           (let ((pdl (make-overlay (line-beginning-position)
                                    (line-beginning-position 2))))
             ;; :background has to be different from the background  
color
             ;; gray1 here is just a little different from black
             (overlay-put pdl 'face '(:underline "gray30" :background  
"gray1"))
             (overlay-put pdl 'modification-hooks
                          ;; these arguments are received from  
modification-hooks
                          '((lambda (overlay after-p begin end  
&optional length)
                              (delete-overlay overlay))))
             (overlay-put pdl 'insert-in-front-hooks
                          '((lambda (overlay after-p begin end  
&optional length)
                              (delete-overlay overlay)))))) t)))))

   Xah
∑ http://xahlee.org/

☄

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

[Stefan Monnier]

> For example, when in w3m mode, which is a mode that allows you to browse the
> web pages, i type “Ctrl+h m” to read the online doc  about the mode's
> features. The result page starts like this:

>     Enabled minor modes: Abbrev Auto-Compression Blink-Cursor
>     Command-Frequency Command-Frequency-Autosave Delete-Selection
>     Desktop-Save Encoded-Kbd File-Name-Shadow Font-Lock Global-Font-
> Lock
>     Line-Number Menu-Bar Mouse-Wheel Recentf Shell-Dirtrack Show-Paren
>     Tooltip Transient-Mark Unify-8859-On-Encoding Utf-Translate-Cjk

>     (Information about these minor modes follows the major mode info.)

> It began by listing “minor-modes”. (What Emacs calls “minor modes”, is
> similar in concept to modern app's preference settings  and
> add-ons features.)

C-h m has historically listed both minor modes and major modes.
Originally, it listed first the major mode than the minor modes, and
people complained that the minor modes were buried and nobody could
notice them.  So we added a header like above to advertize the
minor-mode info that can be found further down.

OT1H I don't think it's as bad as you make it out to be: as you say, you
learn to ignore it, so it does what it's intended to do: teaches you of
the presence of the minor mode info without preventing you from seeing
the major mode info.

OTOH, I agree that many of the above modes shouldn't be there.
More specifically, I think that the above list should only list
buffer-specific information, i.e. only minor modes which are
buffer-local.

The global minor modes could still be present in the *Help* buffer, but
then only at the very end, after the major mode and after the
buffer-local minor modes.


        Stefan

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

[Lars Ingebrigtsen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> OTOH, I agree that many of the above modes shouldn't be there.
> More specifically, I think that the above list should only list
> buffer-specific information, i.e. only minor modes which are
> buffer-local.
>
> The global minor modes could still be present in the *Help* buffer, but
> then only at the very end, after the major mode and after the
> buffer-local minor modes.

I've now done something along these lines in Emacs 29.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Richard M Stallman]

    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

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

[Eli Zaretskii]

> From: Richard M Stallman <rms@gnu.org>
> Date: Fri, 27 Feb 2009 05:10:49 -0500
> Cc: bug-gnu-emacs@gnu.org
> 
> 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?

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

[Lennart Borgman]

On Fri, Feb 27, 2009 at 12:04 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> 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?

A very good suggestion.

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

[Drew Adams]

> > 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?
> 
> A very good suggestion.

Sounds good to me, too.

Actually, we've been around this block before. This discussion 5 years ago:
http://lists.gnu.org/archive/html/emacs-devel/2004-05/msg00275.html
seemed to end with people agreeing that we should show the major mode
information and provide links to show the info for each minor mode (in *Help*).
But no one ever implemented it.

The current suggestion is better in these related ways:
* You can print all mode info at once (with ^L acting as page separator).
* You can show the info for more than one minor mode at a time, in case
comparison helps.

But of course agreement will not (again) mean anything if no one ever implements
it.

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

[Richard M Stallman]

    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

Using hiding is a good idea -- thanks.

I think that partcular way would be inconvenient.  Specifically, it
would be a hassle to initially hide the major mode documentation.
That is what users most often want to see; making them type a command
to expose it would be a gratuitous hassle.

So I suggest putting the partly-hidden minor mode list first,
followed by the totally visible major mode documentation.

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

[Lennart Borgman]

On Sat, Feb 28, 2009 at 12:33 AM, Richard M Stallman <rms@gnu.org> wrote:
>    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
>
> Using hiding is a good idea -- thanks.
>
> I think that partcular way would be inconvenient.  Specifically, it
> would be a hassle to initially hide the major mode documentation.
> That is what users most often want to see; making them type a command
> to expose it would be a gratuitous hassle.
>
> So I suggest putting the partly-hidden minor mode list first,
> followed by the totally visible major mode documentation.


Maybe, but then make the major mode "node" hideable too.

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

[Drew Adams]

>     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
> 
> Using hiding is a good idea -- thanks.
> 
> I think that partcular way would be inconvenient.  Specifically, it
> would be a hassle to initially hide the major mode documentation.
> That is what users most often want to see; making them type a command
> to expose it would be a gratuitous hassle.
> 
> So I suggest putting the partly-hidden minor mode list first,
> followed by the totally visible major mode documentation.

I misread what Eli wrote. I thought he suggested showing the major-mode info, by
default.

That is what I would prefer: 

* Use expandable/contractable entries for each mode (including the major mode).
* Expand the major mode info, by default.
* Put the major mode entry *before* the minor mode entries (like it is now).

IOW, I disagree with Richard about the order - keep the major mode first. We've
already discussed this and decided to put minor-mode info after major mode info.
That's TRT, IMO.

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

[Stefan Monnier]

>     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

> Using hiding is a good idea -- thanks.

> I think that partcular way would be inconvenient.  Specifically, it
> would be a hassle to initially hide the major mode documentation.
> That is what users most often want to see; making them type a command
> to expose it would be a gratuitous hassle.

> So I suggest putting the partly-hidden minor mode list first,
> followed by the totally visible major mode documentation.

I don't think the difference with what we have now is worth
the trouble.  Basically, it's just a question of shortening the "list of
minor modes" at the beginning of the buffer (e.g. by removing global
minor modes from that list).


        Stefan

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

[xah lee]

For me, so far i personally prefer the solution where Ctrl+h m would  
just show the major mode's inline doc.

I think that pretty much fixed it, very simple solution.

Showing the inline doc of major mode is a frequent operation. Perhaps  
daily, or few times per week. Showing the inline doc of ALL minor  
modes, is probably not used much. (personally, i can't think i needed  
it in 10 years)

For people who want to display inline doc of all minor modes at once,  
the describe-mode can work as it is.

As for the ^L char, I think Drew Adam's code works well.

So, overall, for the above, the following simple code does the job.

(defun describe-major-mode ()
   "Show inline doc for current major-mode."
   ;; code by Kevin Rodgers. 2009-02-25
   (interactive)
   (describe-function major-mode))

(global-set-key (kbd "C-h m") 'describe-major-mode)

(require 'pp-c-l)
(pretty-control-l-mode 1)

-----------

For the hide/show solution, i think it's too complex. Complex in UI,  
complex in implementation too. For me, if i wanted to discribe them  
all, i rather prefer they all show, and not having to click each to  
expand, or click on some Expand All button.

Thanks for all the suggestions.

   Xah
∑ http://xahlee.org/

☄

-------------------


On Feb 27, 2009, at 8:34 PM, Stefan Monnier wrote:

>     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

> Using hiding is a good idea -- thanks.

> I think that partcular way would be inconvenient.  Specifically, it
> would be a hassle to initially hide the major mode documentation.
> That is what users most often want to see; making them type a command
> to expose it would be a gratuitous hassle.

> So I suggest putting the partly-hidden minor mode list first,
> followed by the totally visible major mode documentation.

I don't think the difference with what we have now is worth
the trouble.  Basically, it's just a question of shortening the "list of
minor modes" at the beginning of the buffer (e.g. by removing global
minor modes from that list).


         Stefan



☄

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: 2473@emacsbugs.donarmstrong.com,  Eli Zaretskii <eliz@gnu.org>,  xah@xahlee.org
> Date: Fri, 27 Feb 2009 23:34:21 -0500
> 
> >     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
> 
> > Using hiding is a good idea -- thanks.
> 
> > I think that partcular way would be inconvenient.  Specifically, it
> > would be a hassle to initially hide the major mode documentation.
> > That is what users most often want to see; making them type a command
> > to expose it would be a gratuitous hassle.
> 
> > So I suggest putting the partly-hidden minor mode list first,
> > followed by the totally visible major mode documentation.

For the record: I don't mind whether the major mode is first or last,
nor whether it is Initially shown expanded or collapsed.

> I don't think the difference with what we have now is worth
> the trouble.

The difference is twofold, IMO:

  . it presents a UI that's familiar to most users
  . it makes it easy to show initially a very short text without
    hampering user's ability to get to the information she needs most

If that's not worth the trouble, then what is?

(In case it wasn't clear, I wasn't suggesting that we make this change
before Emacs 23.1 is released.)

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

[Lennart Borgman]

On Sat, Feb 28, 2009 at 11:54 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> From: Stefan Monnier <monnier@iro.umontreal.ca>
>> Cc: 2473@emacsbugs.donarmstrong.com,  Eli Zaretskii <eliz@gnu.org>,  xah@xahlee.org
>> Date: Fri, 27 Feb 2009 23:34:21 -0500
>>
>> >     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
>>
>> > Using hiding is a good idea -- thanks.
>>
>> > I think that partcular way would be inconvenient.  Specifically, it
>> > would be a hassle to initially hide the major mode documentation.
>> > That is what users most often want to see; making them type a command
>> > to expose it would be a gratuitous hassle.
>>
>> > So I suggest putting the partly-hidden minor mode list first,
>> > followed by the totally visible major mode documentation.
>
> For the record: I don't mind whether the major mode is first or last,
> nor whether it is Initially shown expanded or collapsed.
>
>> I don't think the difference with what we have now is worth
>> the trouble.
>
> The difference is twofold, IMO:
>
>  . it presents a UI that's familiar to most users
>  . it makes it easy to show initially a very short text without
>    hampering user's ability to get to the information she needs most

And it is very easy to implement ...

> If that's not worth the trouble, then what is?
>
> (In case it wasn't clear, I wasn't suggesting that we make this change
> before Emacs 23.1 is released.)
>
>
>
>
>

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

[Xavier Maillard]

   > From: Richard M Stallman <rms@gnu.org>
   > Date: Fri, 27 Feb 2009 05:10:49 -0500
   > Cc: bug-gnu-emacs@gnu.org
   > 
   > 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.

[...]

   WDYT?

This is a really good suggestion and would greatly improve C-h m
usability (which is the OP's main complaint.

	Xavier
-- 
http://www.gnu.org
http://www.april.org
http://www.lolica.org