Hour 10: The Emacs Help System and Configuration System: General Help Facilities in Emacs

Sams Teach Yourself Emacs in 24 Hours

Hour 10: The Emacs Help System and Configuration System

Sections in this Hour:
General Help Facilities in Emacs		Summary
Getting Extra Help Using the Info System		Q&A
Customizing Emacs's Features		Exercises

Hour 10
The Emacs Help System and Configuration System

The reference manual to Emacs says the following:

"Emacs is the extensible, customizable, self-documenting display editor."

In this hour you will see why they call it customizable and self-documenting. Extensible refers to the fact that users can develop Lisp libraries themselves to drastically change the behavior of Emacs.

I'll start by looking at the different ways you can get information about Emacs and continue by describing one of the new features in Emacs version 20--namely its customizable library, which makes it easy to customize Emacs in several minor ways.

General Help Facilities in Emacs

Several help functions describe and explain almost every part of Emacs. Emacs can answer the following questions:

What does a given key do?

At which key is a given function located?

What does a given function do?

The following questions might arise in the following situations:

I would like to bind C-x C-k to the function yic-kill-current-buffer. What is currently on that key?

In the XEmacs Optimize menu is a submenu called Frame Appearance, which has a function called Frame-local font menu. What does it do?!

You explained that the function edit-kbd-macro is bound to the key C-x C-k, but it seems that my system administrator has bound another function to that key. Can you tell me whether the function edit-kbd-macro is bound to some other key?

In the help pages I found a function called end-of-buffer-other-window. What exactly does it do?

The key to answering each of these questions is C-h, which is the general prefix for all the help commands. If you press C-h twice in GNU Emacs or three times in XEmacs, a buffer appears with all the help commands. In Figure 10.1, you can see the help buffer from GNU Emacs, and, in Figure 10.2, you can see the one from XEmacs.

Figure 10.1
The help buffer from GNU Emacs.

From the help buffer you can click the letter in the left column to execute the function described in the right column. These functions can also be accessed without getting into this menu; simply press C-h and the key from the left column.

Figure 10.2
The help buffer from XEmacs.

The following sections describe the most useful of these functions. You can read about the rest of them in the help buffer.

What Is Bound to This Key?

If you want to bind something to a key, it might be a very good idea to examine what is already bound to the key. You can do that by pressing C-h k (describe-key). This splits the window in two, and, in one window, the key's function will be named and described. If you are searching only for the name of the function that the key executes, you can press C-h c (describe-key-briefly), which lists its name in the minibuffer and, therefore, does not split any windows. Another use for describe-key is to see what a menu item does. Simply press C-h k (describe-key) and select the item from the menu bar.

Caution - In a few cases, however, this doesn't work in Emacs, for reasons too technical to include here.

If you want to know all key bindings active at the moment, press C-h b.

Is There a Function that Does This?

Emacs has hundreds of functions that do almost anything. So if you have a reasonable need, there is a great chance that a function exists that does what you need. Another possibility is that one of the functions might be configured to fulfill your need.

There are two kinds of functions:

Those that are intended to be used right from Emacs

Those that are intended to be used when programming Lisp

Invoke the first kind by pressing the keys they are bound to, if any, or by pressing M-x, and then typing the name. The latter are not accessible from the keyboard. (Actually, they are, but you haven't learned it yet. See Hour 22, "Learning Lisp Basics," for a description on how to use these.)

In Emacs is a function called apropos-command, bound to C-h a in GNU Emacs and C-h A in XEmacs. With this command you can search for other commands and user-definable variables. In XEmacs, however, you will seldom use this command, because a much smarter one exists that will be described shortly. To search for commands only, press C-h a for GNU Emacs and C-h A in XEmacs. If you instead want to search for both commands and variables, you must press C-u C-h a in GNU Emacs and C-u C-h A in XEmacs. Emacs then queries you for a name in the minibuffer and lists all commands (and eventually variables) that match this name. An example of the output can be seen in Figure 10.3.

Figure 10.3
The output from apropos-command (used in GNU Emacs).

In this buffer, you can see all the functions that match the word kill. If you click the middle mouse button on one command, you get the full documentation for the function.

Caution - When you invoke this function, your window is split in two. I've maximized the window shown in Figure 10.3, so that you can see as many help descriptions as possible.

XEmacs has (in my opinion) a much smarter function, called hyper-apropos, bound to the key C-h a. The differences between the ordinary apropos command and this one are that the output is much more compact and the variables and functions are kept in separate. The output from this command can be seen in Figure 10.4.

Figure 10.4
Output from hyper-apropos (used in XEmacs).

Each match takes up only one line, and the description is lined up, which makes it much easier to read. If an asterisk is located in front of a match, this means that the match is either a user command or a user variable, which means that it is meant for you. Nonuser functions and variables are for use only if you program Lisp. Don't let the other symbols in front of each match bother you (that is, a, b, i, l, and m). You will learn in Hour 22 what they are about.

If you click the middle mouse button over a match, the window splits in two and a detailed description for the command is shown. An example of this can be seen in Figure 10.5.

Figure 10.5
The description of a command using hyper-apropos.

If you have found a variable that seems to do what you want, it's time to set it. If you are using Emacs version 19, I've bad news for you: You'll first learn how to set variables in Hour 22. If, on the other hand, you are using Emacs version 20, be patient a bit more; I'll tell you how to configure variables in the final section of this hour.

Is This Function Bound to Any Keys?

Everywhere in this book where a function is described, I provide its default key binding and its name. The default key binding is listed to make it easier for you to use what is described. Fortunately, or perhaps unfortunately (depending on your point of view), your system administrator can change the bindings by default; or you might have loaded a package that changes it (which you haven't told me about). Therefore, the bindings might not be as described. When you find that the key listed isn't executing the described function, it's time to see whether the function might have been moved to another key. To do this, simply press C-h w (where-is) and type the name of the function that you are searching for. Emacs then tells you on which key this function is located, if any. If you use GNU Emacs, this description includes information about whether the function is in any of the menus.

To make XEmacs also tell you about functions located in the menu, insert the following into your .emacs file:


(global-set-key [(control h) (w)] 'sams-where-is)

This line alters the behavior of GNU Emacs.

Tip - You might often want to know if a given keybinding is available elsewhere (for example, in the menus). For this purpose, sams-list-all-bindings exists. When you invoke this function, it asks for a keypress and shows you all the places where the function that's bound to this key is bound elsewhere.

You can bind this function to C-h C-c with the following command:

(global-set-key [(control h) (control c)]

'sams-list-all-bindings

What Does This Function or Variable Do?

Given a function name or variable name, you might want to find out what it is doing. You can do this in one of two ways, depending on the level of accuracy you want for the information.

The low-level way is to press C-h f (describe-function); this asks you for a function name and shows the description in a buffer for itself.

The high-level way is to press C-h C-f. This is the function Info-goto-emacs-command-node in GNU Emacs and Info-elisp-ref in XEmacs. This looks up the function in the info pages and, if it exists, it takes you to the location where it is described. The info pages are described in detail in the next section.