Usability Problems of Emacs's Mode Documentation

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 Python, you can Alt+x describe-mode to quickly see a summary of what command and key shortcuts you have while coding in that language.

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 python mode, help page starts like this:

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, very long:

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 he really want to know what commands and keys 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, 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
• Auto-Encryption

I have used emacs daily for 10 years, half of the minor mode i don't even know what exactly they are.

Also, the page litters Form Feed character “^L” 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.

• Emacs Form Feed ^L Problems

Suggestions

Here's suggestions for describe-mode.

• describe-mode should just show the doc string for the major mode.
• Add a command “describe-minor-modes”.

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.

Solutions

The following is some elisp code that fixes some of the issue above. This is discussed at: “gnu.emacs.help”, 2009-02, 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)

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.