14.4. Navigating Emacs Documentation

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

Table 14-3. Info commands

Keystrokes	Toolbar icon	Command name	Action
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

Keystrokes	Command name	Action
C-h tHelp help-with-tutorial	Run the Emacs tutorial.
C-h i	info	Start the Info documentation reader. If prefaced with C-u, reads an Info file of your choice.
C-h rHelp info-emacs-manual	Opens the Emacs manual.
C-h F Help Find Command in Manual	Info-goto-emacs-command-node	Start Info documentation reader at the node that discusses this command.
C-h K Help Find Key in Manual	Info-goto-emacs-key-command-node	Start Info documentation reader at the node that discusses this key sequence.
C-h n or C-h C-n Help view-emacs-news	View news about recent changes in Emacs.
C-h C-f Help view-emacs-FAQ	View a file of frequently asked questions and their answers about Emacs.
(none) Help search-emacs-glossary	Open a glossary of Emacs terms.
(none) Help emacs-index-search	Search the index of the Emacs user manual.
(none) Help elisp-index-search	Search the index of the Emacs Lisp manual.
C-h EnterHelp Ordering Manuals	view-order-manuals	Displays information about ordering print manuals.
C-h p	finder-by-keyword	Invoke a menu that lets you get information about Emacs Lisp packages available on your system.
C-h C-cHelp describe-copying	View the General Public License (GPL).
C-h C-d Help describe-distribution	View information on ordering Emacs from FSF.
C-h C-p	describe-project	View information on the GNU project. (See the Preface.)
C-h C-w Help describe-no-warranty	View the (non-)warranty for Emacs. Emacs doesn't provide a warranty, hence the name here.
C-h C-t	view-todo	If you're a programmer looking to contribute to the Emacs code base, use this command to view a list of what needs to be done.
C-h C-eHelp view-emacs-problems	Displays the PROBLEMS file, which includes a list of known problems.
C-h h	view-hello-file	View the HELLO file, which displays the word "hello" in numerous languages.
C-h L Help Describe Language Environment	describe-language-environment	Prompts for either default (current environment) or lists possible completions. Menu option shows these choices.
C-h I or C-h C-\ Help describe-input-method	Shows current input method (the default) or, with completion, a list of possible input methods.
C-h C Help Describe Coding System	describe-coding-system	Shows current coding system (the default) or, with completion, lists all available coding systems.