Usability Problems of Emacs's Mode Documentation

By Xah Lee. Date: . Last updated: .

This page details some usability problems of Emacs's doc string for its major mode.

Emacs has a command describe-mode 【Ctrl+h m】. It shows the doc string for the current mode. For example, if you are coding in JavaScript, HTML, Perl, or Python, you can Alt+x describe-mode to quickly see a summary of what feature you have while coding in that language, 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 called transient-mark-mode in emacs. 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 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 doc string could also use some improvement. Here's a excerpt of the doc string 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

Here's suggestions for describe-mode.

For detail about the usability problem of key notation, see: Emacs M-x key Notation vs Alt+x 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 articles related to keys, it is also used thru-out. Example: [ Table of keyboard shortcuts ] [ https://en.wikipedia.org/wiki/Table_of_keyboard_shortcuts ].

Here's a example of suggested result when user calls describe-mode:

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.

Solutions

The following is some elisp code that fixes some of the issue above. This is discussed at: “gnu.emacs.help”, , at http://groups.google.com/group/gnu.emacs.help/browse_frm/thread/c6e9aa01f05ad503

(defun describe-major-mode ()
  "Show doc string 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)

For displaying the “^L” as a thin horizontal line, see:

Note: these fixes need to be in emacs out of the box. Scattered individualistic solutions is useful for those dedicated emacs users who are enthusiastic enough to spend time to dig into tech details and know where to look for code. For them, they already understand emacs terminologies and quirks, and the issues discussed here may be just minor irritations for them. But for most users, these usability problems impede them from using and learning emacs, or continue to use emacs.

Emacs Modernization