14.2. Help Commands

Emacs has many help commands, which are available as standard Emacs commands or as options to the C-h help key. They can be used to find information about commands, keystrokes, variables, modes, and various things about Emacs in general. The most basic help command is C-h C-h (help-for-help). C-h ? also invokes help-for-help. This command causes Emacs to open a *Help* buffer in a window with descriptions of all the help commands. You can type any one of these help keys, or, if you press Space, the *Help* window scrolls down as if you pressed C-v. Any other key aborts the whole process. If you scroll to the bottom of the help documentation, you can type a help key or any other key to abort.

The keys listed in the *Help* are those that, when appended to your help key, run Emacs help commands at any time. Help commands fall into two general categories: those that provide answers to specific questions and those that give general information about Emacs.

You will find the help commands in the former category to be invaluable after you have become comfortable with Emacs. Because it is so large and functionally rich, there will be times when you need to look up a detail such as a keystroke or command name or when you need to do something with Emacs that you don't know exactly how to do. As we've repeated again and again throughout this book, Emacs probably does what you want; you just need to figure out how. The help commands let you find these things out immediately, without leaving Emacs and without being a slave to your reference manual (or even this book).

14.2.1 Detail Information

Let's start with the help commands that are useful when you need to look up a specific detail. You'll probably use the commands listed in Table 14-1 most often.

Table 14-1. Detail information help commands

Keystrokes	Command name	Question answered
C-h c	describe-key-briefly	What command does this keystroke sequence run?
C-h k Help Describe Key	describe-key	What command does this keystroke sequence run, and what does it do?
C-h f Help Describe Function	describe-function	What does this function do?
C-h v Help Describe Variable	describe-variable	What does this variable mean, and what is its value?
C-h m Help Describe Buffer Modes	describe-mode	Tell me about the modes the current buffer is in.
C-h b Help List Key Bindings	describe-bindings	What are all the key bindings for this buffer?
C-h w	where-is	What is the key binding for this command?
C-h s	describe-syntax	What is the syntax table for this buffer?
C-h l	view-lossage	What are the last 100 characters I typed?
C-h e	view-echo-area-messages	What messages have appeared in the minibuffer during this session?

What if you press the wrong key, and something happens to your buffer but you're not sure what? Usually, the safest thing to do is to press C-_ or C-x u (undo). But sometimes this command won't help, for example, a runaway replace-string. If you remember what you typed, you can use C-h c (for describe-key-briefly) to see what command was run; just retype the offending keystroke(s) at the prompt, and Emacs responds with the name of the command bound to the key(s) in the minibuffer. If the command name alone doesn't help, C-h k (for describe-key) pops up a *Help* window with a description of the command as well as its name and key binding. (C-h k and C-h c also help you find out what command a toolbar icon or menu item runs.)

However, if you don't know what keys you pressed, you can type C-h l (for view-lossage). This pops up a *Help* window showing the last 100 keystrokes you typed; the offending ones are likely near the end, and you can use C-h c or C-h k with those keystrokes.

Now suppose you want information on a command that isn't bound to keystrokes. Type C-h f (for describe-function) and enter the name of the command at the prompt; Emacs responds with a *Help* window containing the documentation for that command. If you remember the name of a command but forget its binding, type C-h w (for where-is). This is the "opposite" of C-h c; it shows the key binding for a given command in the minibuffer, or the message command-name is not on any keys if the command has no binding.

You may forget a detail that involves the value of a variable. For example, will Emacs respect or ignore case during a search (the variable case-fold-search)? How often are my buffers being auto-saved (the variable auto-save-interval)? If you type C-h v (for describe-variable) followed by the name of the variable, Emacs puts its value as well as its documentation in a *Help* window. C-h f, C-h w, and C-h v all allow you to use completion when typing command or variable names. C-h f and C-h v are also especially useful to Emacs Lisp programmers; note that C-h f gives you information on all functions, not just those bound to keystrokes as commands.

Another common help situation arises when you use a special mode, such as shell mode or a mode for a programming language or text processor, and you forget a command specific to that mode or some other characteristic such as indentation conventions. If you type C-h m (for describe-mode) in a buffer running the mode, Emacs pops up a *Help* window showing the mode's documentation. Documentation for a mode usually includes all of its local key bindings (for example, all the commands special to the mode and their associated keystrokes), customization variables, and other interesting characteristics.

What if you want to find out all the keyboard commands available in a given mode? C-h b (for describe-bindings) gives you a *Help* window showing all key bindings active in the current buffer, including local (buffer-specific) as well as global ones. It also lists all bindings for mouse actions, menu options, and function keys.

C-h b produces quite a lot of output. If you want to limit this output to only those key bindings with a particular prefix, type that prefix followed by C-h. For example, typing C-x C-h produces a *Help* window listing all key bindings that begin with C-x.

C-h s (for describe-syntax) is a more specialized command, designed for Lisp programmers. It produces a *Help* window with a description of the syntax table (see Chapter 9) active in the current buffer.

14.2.2 Apropos Commands

Another type of help command applies when you want Emacs to do something, but you're not sure exactly what command to use or what variable to set. These are apropos commands, which resemble a rudimentary information retrieval system of the type found at many libraries. The apropos command has several forms, shown in Table 14-2.

Table 14-2. Apropos commands

Keystrokes	Command name	Question answered
C-h aHelp apropos-command	What commands include this word?
(none) Help apropos-variable	What variables include this regular expression?
(none) Help apropos-value	What variables are set to this regular expression?
(none) Help apropos-documentation	Where is this regular expression mentioned in the documentation?
(none) Help apropos	What functions and variables involve this regular expression?

All apropos commands prompt for regular expressions (an ordinary text string will work, but you can create more powerful searches using regular expressions; see Chapter 11 for details). When you type C-h a followed by a regular expression, Emacs finds all the commands that match it; it displays their key bindings (if any) and the first lines of their documentation in an *Apropos* window that is in Apropos mode. This mode displays hyperlinked help. If you click on a bolded item using your middle mouse button or move the cursor there and press Enter, Emacs displays more information.

As always, if you are leery of using regular expressions, use regular search strings as long as you stick to nonspecial characters. For example, if you want to know what replace commands Emacs supports, press C-h a and then type replace; Emacs displays a list of information on the following commands:

• dired-do-query-replace

• ebrowse-tags-query-replace

• ethio-replace-space

• map-query-replace-regexp

• query-replace

• query-replace-regexp

• query-replace-regexp-eval

• replace-buffer-in-windows

• replace-rectangle

• replace-regexp

• replace-string

• tags-query-replace

If you have ever used an information retrieval system, you already know that some skill is needed to use such a system effectively. You need to choose your concepts (search strings) carefully, so that they aren't too general (too much output to wade through) or too specific (too little output, making it less likely that you get the information you want). This problem is compounded when you use the apropos command, which is the same as apropos-command except that it reports on all functions (including internal Emacs functions) and variables as well as commands.

If you type in a search string that is too general, Emacs produces an enormous buffer of help information. For example, invoking apropos-command with the argument "buffer" results in output listing well over two hundred Emacs commands. In general, you may have to invoke the apropos commands a few times to get the information you want (in terms of size as well as relevance).

The apropos command itself is usually overkill, unless you are a Lisp programmer who needs information on noncommand functions (see Chapter 11 for details on this use of apropos). Use a more specific command when possible. For example, to get information on variables, use apropos-variable. To find out about variables related to auto-saving, type M-x apropos-variable Enter auto-save Enter. Emacs responds with information about the variables auto-save-default, auto-save-file-format, auto-save-file-name-transforms, auto-save-interval, auto-save-list-file-prefix, auto-save-timeout, auto-save-visited-file-name, and delete-auto-save-files. To find the value and full description of one of these variables, move to the *Apropos* window and either click with the middle mouse button or move to the desired variable and press Enter.