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).
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 → Describe Key |
describe-key |
What command does this keystroke sequence run, and what does it do? |
C-h f Help → Describe → Describe Function |
describe-function |
What does this function do? |
C-h v Help → Describe → Describe Variable |
describe-variable |
What does this variable mean, and what is its value? |
C-h m Help → Describe → Describe Buffer Modes |
describe-mode |
Tell me about the modes the current buffer is in. |
C-h b Help → Describe → 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.
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 a Help → Search Documentation → Find Commands by Name |
apropos-command |
What commands include this word? |
(none) Help → Search Documentation → Find Options by Name |
apropos-variable |
What variables include this regular expression? |
(none) Help → Search Documentation → Find Options by Value |
apropos-value |
What variables are set to this regular expression? |
(none) Help → Search Documentation → Search Documentation Strings |
apropos-documentation |
Where is this regular expression mentioned in the documentation? |
(none) Help → Search Documentation → Find Any Object by Name |
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.