Learning GNU Emacs, 3rd Edition

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*

*Help*

The keys listed in the

*Help*

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

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*

However, if you don't know what keys you pressed, you can type C-h l (for view-lossage). This pops up a

*Help*

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*

command-name is not on any keys

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*

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*

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*

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*

C-h s (for describe-syntax) is a more specialized command, designed for Lisp programmers. It produces a

*Help*

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

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*

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*

Once upon a time, to get access to Emacs documentation, you ordered manuals from FSF. You can still do so if you like printed documentation (as we do) and would like to support the FSF, but most of the documentation you will ever want or need is at your fingertips right in Emacs.

14.4.1 Using Info to Read Manuals

Most GNU documentation (including Emacs documentation) is in texinfo format and designed to be read in the Info documentation reader. Typing C-h i (for info) puts you at the top-level of the Info tree. You'll see that Emacs is just one choice of many. In Info, documentation is organized as trees of information called nodes. If you want information on a topic, you can select its tree; the nodes of the tree contain information on subtopics, subsubtopics, etc., organized hierarchically.

When you type C-h i, you see a read-only buffer containing the directory node of the Info system in a window in Info mode. If you press h while in Info, you get a tutorial on Info analogous to the one described earlier for basic Emacs commands.

You're probably better off typing C-h r, which sends you directly to the Emacs manual.

Type: C-h r

Emacs displays the table of contents for the Emacs manual.

Note that the icons are almost completely different in Info mode. Later in this section, Table 14-3 lists them, along with the keystrokes needed for navigating in this mode.

Info is relatively simple, yet complex enough to have its own tutorial. Typing h sends you through a tutorial to acquaint you with the main commands.

To select a menu option (you see a * next to these), move to that option. Obviously, moving with the mouse is one method; you then select the option using the middle mouse button. Alternatively, move to the option by pressing Tab, and then press Enter.

Move to Minibuffer (you'll need to scroll down), and then press Enter.

The Minibuffer topic appears.

If you want to read through the whole topic, you can press Space to scroll down. Space is helpful for continuous reading because after you complete a topic, it moves you to the next node at this level. If you read all of this topic, you'll learn more about the minibuffer than you ever thought possible.

If you press u twice (to move up a level), you'll move back to the Emacs table of contents. The up arrow icon on the toolbar does the same thing. To accomplish this with a single keystroke, type t (for Info-top-node) or click on the house toolbar icon. That command takes you to the top level in one move, no matter how far down the Info tree you've traveled.

To search for a particular topic, type i or click on the toolbar icon that shows a finger pointing at a piece of paper.

Type: i

Emacs prompts for an index topic.

Type: macro Enter

Emacs brings up the first topic related to macros.

Type a comma: ,

Emacs moves to the next macro-related topic in the index.

As you step through index entries in this way, it's helpful to look at the top of the screen to see what topic you're in. You might want to move up a node (or to the previous or next node) to get a better view of the topic at hand rather than navigating to the next index entry by typing another comma.

Navigating through Info can take some practice. For example, one might think that the command p (for Info-prev)[97] would behave rather like a web browser back button (especially given that the toolbar icon for this command looks like one). Previous in this case means relative to the Info documentation tree, not to your session (though it may appear that way sometimes). It means that you want to move to the previous item at this level. To move back to the previous screen in your session, use l (for Info-last), shown on the toolbar with a curved arrow icon (like the icon for undo in other modes). This command behaves like a web browser back button.

The commands C-h F (for Info-goto-emacs-command-node) and C-h K (for Info-goto-emacs-key-command-node) let you use Info in a more focused way. They are essentially the Info equivalents of C-h f (for describe-function) and C-h k (for describe-key), respectively: they start up the Info system and go directly to the documentation for the command (for C-h F) or the keystroke(s) (for C-h K) you give as an argument.

Table 14-3. Info commands

Tab

Info-next-reference

Move to the next menu item or cross-reference.

Space

Info-scroll-up

Scroll the screen; move to the next topic at this level when finished.

Del or PgUp

Info-scroll-down

Scroll backward.

p

Info-prev

Move to the previous topic at this level (not like a browser back button). If there is no previous topic, move up a level.

u

Info-up

Move up a level.

n

Info-next

Move to the next topic at this level.

i

Info-index

Search the index for a topic.

,

Info-index-next

Go to the next topic in the index.

m

Info-menu

Select a menu item through the keyboard.

q

Info-exit

Quit info.

s

Info-search

Search for a regular expression.

g

Info-goto-node

Go to a specified node.

t

Info-top-node

Go to the top node.

l

Info-last

Go to the last node you visited (like a browser back button).

h

Info-help

Start the info tutorial.

14.4.2 FAQ, News, and Antinews

To display the Frequently Asked Questions (FAQ) file, type C-h f. This file is in Info format.

Perhaps the most important of the remaining Emacs help commands for hard-core users and customizers is C-h n (for view-emacs-news), which visits the NEWS file that comes with Emacs. This file contains a history of changes made to Emacs since the last major version; for example, all changes in Version 20.1 and following up to the latest minor version (which in our case is Version 21.3.5, though the file says 21.4). This can be a very long file if there have been several minor releases since the last major version—in our case, the file is 12,886 lines long. If you want to look through it for changes to a specific aspect of Emacs, use an appropriate search command. But if you just want to skim it, note that this file was intended for use with outline mode: topics are introduced on lines beginning with *, and subtopics are introduced on lines beginning with **. Use outline mode commands to skim the file; see Chapter 7 for information. The outline mode command hide-body displays the main topics and hides the text; show-all redisplays all the text as well.

An entertaining approach to learning about the latest release is Antinews. This file takes the viewpoint that Emacs has been downgraded, in our case from 21.4 to 21.3. It takes you through all the features that have been ripped from Emacs 21.4 to create Emacs 21.3. Antinews is a menu item on the first page of the Emacs manual you reach via C-h r.

Table 14-4 summarizes commands relating to reading documentation, getting general information about Emacs, and language encoding issues.

Table 14-4. Documentation, general information, and encoding options

We saw an example of Emacs's completion facility in Chapter 1. Completion is more than just a feature: it is a general principle in the design of Emacs. It can be articulated as follows:

In other words, you can type in the shortest unambiguous prefix and tell Emacs to figure out the rest of the name. By "shortest unambiguous prefix," we mean "enough of the name, starting from the beginning, to distinguish it from the other possibilities." Several important things in Emacs have names that are chosen from a finite number of possibilities, including the following:

• Commands

• Files in a given directory

• Buffers

• Emacs variables

Most of the time, completion is available when you are prompted for a name of something in the minibuffer. While you are typing in the name, you can use three keys to tell Emacs to help complete it for you: Tab, Space, and question mark (?). Their functions are shown in Table 14-5.

Table 14-5. Completion keys

*Completions*

You will probably find Tab to be the most useful.

As a running example, assume you have typed C-x C-f to visit a file, and the file you want to visit is a C program called program.c. Let's say you type pro and press Tab; Emacs responds by completing the name to the full program.c. If you press Space, Emacs completes only as far as program. After Emacs completes the name, you can press Enter to visit the file.

How much of the name do you need to type in before you can use completion? That depends on the other possible choices in the given situation. If program.c were the only file in your directory, you could just type p and press Tab.[98] If there were other files in your directory and none of them has a name beginning with p, you could do the same thing. But if you had a file called problem.c, you would have to type prog before you pressed Tab; in this case, prog is the shortest unambiguous prefix. If you just type in pro and press Tab, Emacs responds with a

*Completions*

As another example, let's say you have documentation for your C program in the file program.txt, and you want to visit it. You press C-x C-f and type prog at the prompt, followed by Tab. Emacs completes out to program.. At this point, you can type t and press Tab again; Emacs completes the entire program.txt. In other words, you can use completion repeatedly when specifying a name.

Finally, let's say you also have a file in your directory called simply program, which is the result of compiling your C file, but you still want to visit the documentation file. You type prog and press Tab; Emacs completes out to program. (including the period). At this point, Tab and Space do different things. If you press Tab again, Emacs responds with the message

[Complete, but not unique]

Completion works the same way with buffer names, for example, when you type C-x b to switch to another buffer in the current window. It also works with command names when you type M-x—but with one added feature. Notice that when you specify a file or buffer name, it is possible that the file or buffer you want doesn't yet exist (for example, when you want to create a new file). In this case, of course, you must type in the entire file or buffer name and press Enter. But when you type M-x for a command, there is no possibility of the command not existing. Therefore, Emacs automatically attempts to do completion on command names when you press Enter.

For example, if you want to put a buffer for a text file in auto-fill mode (see Chapter 2), you can type M-x auto-f and press Enter instead of typing the entire M-x auto-fill-mode. If you type in a nonunique (ambiguous) prefix of a command name—for example, if you type M-x aut—and press Enter, then Enter acts just like Tab; in this case, it completes out to auto. If you press Enter again, Emacs responds with a

*Completions*

Completion on command names with Enter is very convenient. After you have used Emacs for a while, you will become familiar with the shortest unambiguous prefixes for commands you use often, and you can save a considerable amount of typing by using these prefixes instead of the full names.[99]

Emacs can also do completion on the names of Emacs variables. In Chapter 2, and elsewhere, we saw how you can use M-x set-variable to change the values of Emacs variables. The Enter feature just described works on variables as well as commands; therefore, you can use completion, including Enter, when doing M-x set-variable. Actually, commands and variables are both special kinds of Emacs Lisp symbols, and Emacs can do completion with Enter on all kinds of Lisp symbols. Completion on Lisp symbols comes in handy when you are using some of the help commands described earlier in this chapter.

14.5.1 Customizing Completion

If you have read Chapter 10 and are comfortable with setting Emacs variables, you should know that a few variables can customize the way Emacs does completion. The variable completion-auto-help determines whether a

*Completions*

*Completions*

[Next char not unique]

If you are a programmer or if you use text formatters like LATEX , you will create files that are not meant for humans to read, such as object files created by compilers and print files created by text formatters. Ideally, you wouldn't want Emacs to bother with these files when you are doing completion; for example, if you have the files program.c and program.o (object-code output from the compiler), you want Emacs to recognize only the former. Emacs does have a feature that deals with this; indeed, you may already have noticed that in this kind of situation, if you type program and press Tab, Emacs ignores program.o and completes out to program.c. The variable completion-ignored-extensions controls this; it is a list of filename suffixes that Emacs ignores during filename completion. By default, the list includes tilde (

~

You can add your own "ignored" suffix to the list by putting a line of this form in your .emacs file:

(setq completion-ignored-extensions

   (cons "suffix" completion-ignored-extensions))

For example, let's say you are doing text processing with a printer that prints PostScript, and your text processor produces print files with the suffix .ps. If you don't want to look at these files, put the following line in your .emacs file:

(setq completion-ignored-extensions

   (cons ".ps" completion-ignored-extensions))

Finally, you can tell Emacs to ignore case distinctions when doing completion by setting the variable completion-ignore-case to t (or any value other than nil). Its default value is nil, meaning that Emacs respects case distinctions.