Debra Cameron - Learning GNU Emacs, 3rd Edition

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 cor C-h kwith 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 vall allow you to use completion when typing command or variable names. C-h fand C-h vare also especially useful to Emacs Lisp programmers; note that C-h fgives 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 bproduces 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-hproduces 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.

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 aproposcommands, which resemble a rudimentary information retrieval system of the type found at many libraries. The aproposcommand has several forms, shown in Table 14-2.

Table 14-2. Apropos commands

All aproposcommands 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 afollowed 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 aand 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 aproposcommand, which is the same as apropos-commandexcept 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-commandwith the argument "buffer" results in output listing well over two hundred Emacs commands. In general, you may have to invoke the aproposcommands a few times to get the information you want (in terms of size as well as relevance).

The aproposcommand itself is usually overkill, unless you are a Lisp programmer who needs information on noncommand functions (see Chapter 11for 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.