Browse Info: the built-in documentation system
Emacs comes with a great deal of documentation, including a complete manual for users. The manual is written in Info, which is the GNU Project's text-based hypertext documentation system (it precedes the World Wide Web). Although the GNU Info system also has an eponymous, standalone reader application (and many third-party reader applications), you can also read Info documents inside Emacs.
Info documents have a hierarchical, tree-like structure. The basic unit of an Info document is the node, which is the rough equivalent to an HTML page on a Web site; each node describes a topic or subtopic of that Info document.
Nodes contain the text of the document; nodes can also contain any number of cross references, which are hyperlinks that take you to the nodes they reference. The newer versions of Emacs show cross references by highlighting them in color; but you can tell cross references even if you're in a text terminal, because they always begin with the text *Note: and then give the name of the node they refer to.
Nodes can also end with a menu, which is a list of cross-reference links, usually of all the nodes that exist as subtopics beneath the current node. Menus begin with the text * Menu: and then list the cross references on the lines immediately following.
Every Info document has a Top node, which is the starting point for that document tree—think of it as the table of contents in a printed book. The Top node contains a main menu for that document, showing all the major subdivisions in the document. Documents usually also have an Index node containing a list of all nodes in that document.
The GNU Info system keeps a directory of all Info documents stored on the system in a special, main Top node called the Directory node. When new Info documents are installed on the system (often in the /usr/share/info directory, but this differs across different UNIX implementations), they're added to this node.
With the exception of the Directory node, nodes always have an Up node that brings you to the topic the current node is a subtopic of; the Up node of a document's Top node is the main Directory node. Nodes can also have other nodes designated as their Next and Previous nodes—those are nodes that are at a parallel level to the current node in the document tree.
Figure 5 illustrates the GNU Info system's node structure, showing a simplified view of the Directory node with example Info documents.
Figure 5. Sample GNU Info-document hierarchy
info function (bound to
C-h i) starts Info, opening to the main Directory
node containing links to all the Info documents installed on the system.
Start Info by typing
This opens a new *info* buffer containing your system's main Info Directory node. This is the highest Top node in the system. There are no nodes above it, nor does it have a Next or Previous node; the only nodes available are the ones in its menu.
Use the cursor keys to move down to the menu item for the Emacs node—it begins with the text * Emacs: —and press Enter to select it.
When you do this, Info opens the Top node of the Emacs manual, as in Figure 6. It has an Up node (the Directory node you just came from) and a Next node, which is the first chapterM in the manual. It also has a Previous node, which in this case is also the Directory node.
Figure 6. Viewing the GNU Emacs manual in Info
There are a few ways to move through a node. Use the PgUp and PgDn keys to scroll through a node a screen at a time. When you use these keys, you scroll only through the current node—once you reach the top or bottom of the node, you stop scrolling in that direction.
Try using PgDn to move through the node you're in, showing the main menu of the Emacs manual.
You can also use the Spacebar and Backspace keys to scroll forward and backward through the node and automatically move between nodes: If you encounter a menu while scrolling forward in the node, you immediately move to the first node referenced in that menu; and if you encounter the top of the node while scrolling backward in the node, you immediately move to the top of that node's Previous node.
When you use these two keys to scroll through nodes, you can cycle through an entire Info document. However, you can't move to another document in the Directory node this way. Note in Figure 5 how all menu items form parallel links that you can move between, except for menu items in the Directory node. In this example, suppose you're at the Gizmo manual node: Pressing the Spacebar repeatedly takes you through that node to the following nodes:
Turning them on
Turning them off
Try pressing the Spacebar several times to move to the Next node and then through it and several other nodes.
You can also move to the Next and Previous nodes at any time by pressing N and P, respectively.
To move to the Up node, press U; and to move to the last node you visited before the current node, press L.
To follow a particular item in a menu or a cross reference given somewhere in a
node, move the cursor onto it and press Enter. You can also use the mouse
B2 on the link.
Try moving through the Emacs documentation using the commands you've just learned.
You can use several techniques to search inside Info. One way uses the
Info-index command, bound to the I key, which
searches the Index node of that document for the given text.
Try searching for info in the Emacs manual:
Press I to run the
Index topic:prompt, type
When you do this, Emacs displays the page of the manual that discusses using Info.
You can also search incrementally through the current node by using the Emacs
isearch-forward function, which is bound to
C-s and was described earlier in this series.
Search forward through the current node for info: Type
C-s info to move the cursor to the next instance of
the text, and then type
C-s repeatedly to cycle
through all the instances of info in that node.
To search for text through the current node and all other nodes, use the
Info-search function, bound to the S key. It moves to
the next instance of the given text anywhere in the Info document.
Try searching for info again:
M->to move to the end of the node.
Press S to run the
In the minibuffer, type
When you do this, Emacs moves to the next instance of the text info, which occurs in another node in the document.
There are a few different ways to put Info behind you.
To switch to another buffer and move the Info buffer to the background of the buffer list, press Q.
Try it now, and see how Emacs displays another buffer; then type
C-x b *info* Enter
to move back to the *info*
To kill the *info* buffer, type
k (just as you
would with any buffer). *info* is removed from your buffer list; to view it
C-h i to start from the beginning.
Table 3 lists the various keystroke commands that are available in Info mode and describes their function.
Table 3. Summary of Emacs Info mode commands
||This command opens a hands-on Info tutorial in a new buffer.|
||This command moves to the last buffer you visited, putting the *info* buffer in the end of the buffer list.|
||This command follows the cross reference at or near point.|
||This command moves to the current node's Next node.|
||This command moves to the current node's Previous node.|
||This command moves to the current node's Up node.|
||This command moves to the Directory node.|
||This command moves to the last node you visited.|
||This command moves to the Top node of the current document.|
||This command moves to the final node pointed to in the current document.|
||This command moves forward in the current node by a single screen; if at the end of the node, then move to the Next node.|
||This command moves backward in the current node by a single screen; if at the beginning of the node, then move to the Previous node.|
||This command goes to the beginning of the current node.|
||This command searches forward in the current Info document for a given regexp.|
||This command moves the cursor forward to the first cross reference.|
||This command moves the cursor backward to the last cross reference.|