Weekly Emacs tip #8: Getting help: the C-h prefix

This week, another “tip” that is both a tip and some background information.

Emacs has been called the self-documenting editor. The first time may very well have been in the 1981 paper by Richard Stallman titled EMACS the extensible, customizable self-documenting display editor (https://doi.org/10.1145/872730.806466). The Emacs manual describes it in the following way:

Self-documenting means that at any time you can use special commands, known as help commands, to find out what your options are, or to find out what any command does, or to find all the commands that pertain to a given topic.

The “self” part does not mean that documentation is magically and/or automatically written or generated. It is the task of the function or package developer to provide this documentation. If this is done properly, the Emacs help machinery will be at your command.

The C-h prefix is your gateway to the Emacs help system:

• C-h k (the describe-key function): invoking this command asks you to type a keybinding, for which it will then show the available help. For example, C-h k C-x C-s will show the help for the save-buffer command. This is the way to find out which function is bound to a given key combo.
• C-h m (describe-mode) displays information of the current major mode and any loaded minor modes
• C-h b (describe-bindings): shows a list of all keybindings defined for the current mode (major and minor).

• C-h v (describe-variable): prompts for the name of an Emacs variable and then shows its help. For example, C-h v mouse-yank-at-point (see tip #4) shows me:

  mouse-yank-at-point is a variable defined in ‘mouse.el’.

  Its value is t Original value was nil

  If non-nil, mouse yank commands yank at point instead of at click. This also allows yanking text into an isearch without moving the mouse cursor to the echo area.

  You can customize this variable. Probably introduced at or before Emacs version 29.1.

  Notice that it tells me the variable’s value is t, and that it has been changed from the default nil value. The second-to-last line shows that this variable can also be changed using Emacs’s Customize menu system.

• C-h f (describe-function): asks you for a function name, and then, as the name says, shows you what a given function does. Remember from last week’s tip that in Emacs, many things happen through function calls and not all functions are bound to a keyboard shortcut. For example, to get help for the rgrep function, use C-h f rgrep. Here are the first few lines of the help:

  rgrep is an autoloaded interactive native-compiled Lisp function in ‘grep.el’.

  It can be invoked from the menu: Tools → Recursive Grep…

  (rgrep REGEXP &optional FILES DIR CONFIRM)

  Recursively grep for REGEXP in FILES in directory tree rooted at DIR.

  Notice that it shows you in which file the function is defined (and the name is a clickable link), and that it can also be called via the “Tools” menu. Next, it shows you the arguments the function accepts, and on the last line a short description of what the function does (the full output has more information below this).

Each of these help commands show their output in a newly created window (in Emacs terminology, not what most people consider a window), so knowing your window management commands will be helpful :-). Maybe that is something for another tip…