I've cleaned up and edited the page a bit. Now it's on my site here:
• Usability Problems Of Emacs's Mode Documentation
http://xahlee.org/emacs/modernization_mode_doc.html
Here's a plain text version:
-------------------------------
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.)
Note that it first show users a bunch of meta info about “minor-
modes”. (most “minor modes”'s functionality are what today called
preference settings in other apps, while some minor modes provides
additional features such as abbreviation, templates, etc.)
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.
These minor modes, filled with emacs technicalities and terminologies
specific to emacs, are not relevant to users. 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 key notation, such as “C-u C-u”, “RET”, are hard to read,
especially when used together with shortcut keys without 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.
Xah
∑ http://xahlee.org/
☄