Learning GNU Emacs, Third Edition

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.

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.

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.

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)^[1] 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.

^[1] These command names are case-sensitive. For example, completion won't find them if you type them with a lowercase i.

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.

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.