Go to the first, previous, next, last section, table of contents.


2. Info for Experts

This chapter describes various Info commands for experts. (If you are using a stand-alone Info reader, there are additional commands specific to it, which are documented in several chapters of section `GNU Info' in GNU Info.)

This chapter also explains how to write an Info as distinct from a Texinfo file. (However, in most cases, writing a Texinfo file is better, since you can use it to make a printed manual or produce other formats, such as HTML and DocBook, as well as for generating Info files.) See section `Overview of Texinfo' in Texinfo: The GNU Documentation Format.)

2.1 Advanced Info Commands

Here are some more Info commands that make it easier to move around.

g goes to a node by name

If you know a node's name, you can go there by typing g, the name, and RET. Thus, gTopRET would go to the node called `Top' in this file. (This is equivalent to t, see section 1.7 Some intermediate Info commands.) gAdvancedRET would come back here. g in Emacs runs the command Info-goto-node.

Unlike m, g does not allow the use of abbreviations. But it does allow completion, so you can type TAB to complete a partial node name.

To go to a node in another file, you can include the file name in the node name by putting it at the front, in parentheses. Thus, g(dir)TopRET would go to the Info Directory node, which is the node `Top' in the Info file `dir'. Likewise, g(emacs)TopRET goes to the top node of the Emacs manual.

The node name `*' specifies the whole file. So you can look at all of the current file by typing g*RET or all of any other file with g(filename)RET.

1 -- 9 choose a menu subtopic by its number

If you begrudge each character of type-in which your system requires, you might like to use the commands 1, 2, 3, 4, ..., 9. They are short for the m command together with a name of a menu subtopic. 1 goes through the first item in the current node's menu; 2 goes through the second item, etc. In the stand-alone reader, 0 goes through the last menu item; this is so you need not count how many entries are there. In Emacs, the digit keys run the command Info-nth-menu-item.

If your display supports multiple fonts, and you are using Emacs' Info mode to read Info files, the `*' for the fifth menu item stands out, either in color or in some other attribute, such as underline, and so is the `*' for the ninth item; this makes it easy to see at a glance which number to use for an item.

Some terminals don't support colors or underlining. If you need to actually count items, it is better to use m instead, and specify the name, or use TAB to quickly move between menu items.

e makes Info document editable

The Info command e changes from Info mode to an ordinary Emacs editing mode, so that you can edit the text of the current node. Type C-c C-c to switch back to Info. The e command is allowed only if the variable Info-enable-edit is non-nil.

The e command only works in Emacs, where it runs the command Info-edit. The stand-alone Info reader doesn't allow you to edit the Info file, so typing e there goes to the end of the current node.

2.2 How to search Info documents for specific subjects

The commands which move between and inside nodes allow you to read the entire manual or its large portions. But what if you need to find some information in the manual as fast as you can, and you don't know or don't remember in what node to look for it? This need arises when you use a manual as a reference, or when it is impractical to read the entire manual before you start using the programs it describes.

Info has powerful searching facilities that let you find things quickly. You can search either the manual indices or its text.

Since most subjects related to what the manual describes should be indexed, you should try the index search first. The i command prompts you for a subject and then looks up that subject in the indices. If it finds an index entry with the subject you typed, it goes to the node to which that index entry points. You should browse through that node to see whether the issue you are looking for is described there. If it isn't, type , one or more times to go through additional index entries which match your subject.

The i command finds all index entries which include the string you typed as a substring. For each match, Info shows in the echo area the full index entry it found. Often, the text of the full index entry already gives you enough information to decide whether it is relevant to what you are looking for, so we recommend that you read what Emacs shows in the echo are before looking at the node it displays.

Since i looks for a substring, you can search for subjects even if you are not sure how they are spelled in the index. For example, suppose you want to find something that is pertinent to commands which complete partial input (e.g., when you type TAB). If you want to catch index entries that refer to "complete", "completion", and "completing", you could type icompletRET.

Info documents which describe programs should index the commands, options, and key sequences that the program provides. If you are looking for a description of a command, an option, or a key, just type their names when i prompts you for a topic. For example, if you want to read the description of what the C-f key does, type iC-fRET. Here C-f are 3 literal characters `C', `-', and `f', not the "Control-f" command key you type inside Emacs to run the command bound to C-f.

In Emacs, i runs the command Info-index.

The s command allows you to search a whole file for a string. It switches to the next node if and when that is necessary. You type s followed by the string to search for, terminated by RET. To search for the same string again, just s followed by RET will do. The file's nodes are scanned in the order they are in in the file, which has no necessary relationship to the order that they may be in the tree structure of menus and `next' pointers. But normally the two orders are not very different. In any case, you can always do a b to find out what node you have reached, if the header is not visible (this can happen, because s puts your cursor at the occurrence of the string, not at the beginning of the node).

In Emacs, Meta-s is equivalent to s. That is for compatibility with other GNU packages that use M-s for a similar kind of search command. Both s and M-s run in Emacs the command Info-search.

2.3 Adding a new node to Info

To add a new topic to the list in the Info directory, you must:

  1. Create some nodes, in some file, to document that topic.
  2. Put that topic in the menu in the directory. See section 2.4 How to Create Menus.

Usually, the way to create the nodes is with Texinfo (see section `Overview of Texinfo' in Texinfo: The GNU Documentation Format); this has the advantage that you can also make a printed manual or HTML from them. You would use the `@dircategory' and `@direntry' commands to put the manual into the Info directory. However, if you want to edit an Info file manually and install it manually, here is how.

The new node can live in an existing documentation file, or in a new one. It must have a `^_' character before it (invisible to the user; this node has one but you cannot see it), and it ends with either a `^_', a `^L' ("formfeed"), or the end of file.(2)

The `^_' starting a node must be followed by a newline or a `^L' newline, after which comes the node's header line. The header line must give the node's name (by which Info finds it), and state the names of the `Next', `Previous', and `Up' nodes (if there are any). As you can see, this node's `Up' node is the node `Expert Info'. The `Next' node is `Menus'.

The keywords Node, Next, Previous, and Up may appear in any order, anywhere in the header line, but the recommended order is the one in this sentence. Each keyword must be followed by a colon, spaces and tabs, and then the appropriate name. The name may be terminated with a tab, a comma, or a newline. A space does not end it; node names may contain spaces. The case of letters in the names is insignificant.

A node name has two forms. A node in the current file is named by what appears after the `Node: ' in that node's first line. For example, this node's name is `Add'. A node in another file is named by `(filename)node-within-file', as in `(info)Add' for this node. If the file name starts with "./", then it is relative to the current directory; otherwise, it is relative starting from the standard directory for Info files of your site. The name `(filename)Top' can be abbreviated to just `(filename)'. By convention, the name `Top' is used for the "highest" node in any single file--the node whose `Up' points out of the file. The `Directory' node is `(dir)', it points to a file `dir' which holds a large menu listing all the Info documents installed on your site. The `Top' node of a document file listed in the `Directory' should have an `Up: (dir)' in it.

The node name * is special: it refers to the entire file. Thus, g* shows you the whole current file. The use of the node * is to make it possible to make old-fashioned, unstructured files into nodes of the tree.

The `Node:' name, in which a node states its own name, must not contain a file name, since when Info searches for a node, it does not expect a file name to be there. The `Next', `Previous' and `Up' names may contain them. In this node, since the `Up' node is in the same file, it was not necessary to use one.

Note that the nodes in this file have a file name in the header line. The file names are ignored by Info, but they serve as comments to help identify the node for the user.

2.4 How to Create Menus

Any node in the Info hierarchy may have a menu---a list of subnodes. The m command searches the current node's menu for the topic which it reads from the terminal.

A menu begins with a line starting with `* Menu:'. The rest of the line is a comment. After the starting line, every line that begins with a `* ' lists a single topic. The name of the topic--what the user must type at the m's command prompt to select this topic--comes right after the star and space, and is followed by a colon, spaces and tabs, and the name of the node which discusses that topic. The node name, like node names following `Next', `Previous' and `Up', may be terminated with a tab, comma, or newline; it may also be terminated with a period.

If the node name and topic name are the same, then rather than giving the name twice, the abbreviation `* name::' may be used (and should be used, whenever possible, as it reduces the visual clutter in the menu).

It is considerate to choose the topic names so that they differ from each other very near the beginning--this allows the user to type short abbreviations. In a long menu, it is a good idea to capitalize the beginning of each item name which is the minimum acceptable abbreviation for it (a long menu is more than 5 or so entries).

The nodes listed in a node's menu are called its "subnodes", and it is their "superior". They should each have an `Up:' pointing at the superior. It is often useful to arrange all or most of the subnodes in a sequence of `Next' and `Previous' pointers so that someone who wants to see them all need not keep revisiting the Menu.

The Info Directory is simply the menu of the node `(dir)Top'---that is, node `Top' in file `.../info/dir'. You can put new entries in that menu just like any other menu. The Info Directory is not the same as the file directory called `info'. It happens that many of Info's files live in that file directory, but they do not have to; and files in that directory are not automatically listed in the Info Directory node.

Also, although the Info node graph is claimed to be a "hierarchy", in fact it can be any directed graph. Shared structures and pointer cycles are perfectly possible, and can be used if they are appropriate to the meaning to be expressed. There is no need for all the nodes in a file to form a connected structure. In fact, this file has two connected components. You are in one of them, which is under the node `Top'; the other contains the node `Help' which the h command goes to. In fact, since there is no garbage collector, nothing terrible happens if a substructure is not pointed to, but such a substructure is rather useless since nobody can ever find out that it exists.

2.5 Creating Cross References

A cross reference can be placed anywhere in the text, unlike a menu item which must go at the front of a line. A cross reference looks like a menu item except that it has `*note' instead of `*'. It cannot be terminated by a `)', because `)''s are so often part of node names. If you wish to enclose a cross reference in parentheses, terminate it with a period first. Here are two examples of cross references pointers:

*Note details: commands.  (See *note 3: Full Proof.)

These are just examples. The places they "lead to" do not really exist!

2.5.1 The node reached by the cross reference in Info

This is the node reached by the cross reference named `Cross'.

While this node is specifically intended to be reached by a cross reference, most cross references lead to nodes that "belong" someplace else far away in the structure of an Info document. So you cannot expect this node to have a `Next', `Previous' or `Up' links pointing back to where you came from. In general, the l (el) command is the only way to get back there.

>> Type l to return to the node where the cross reference was.

2.6 Quitting Info

To get out of Info, back to what you were doing before, type q for Quit. This runs Info-exit in Emacs.

This is the end of the basic course on using Info. You have learned how to move in an Info document, and how to follow menus and cross references. This makes you ready for reading manuals top to bottom, as new users should do when they learn a new package.

Another set of Info commands is useful when you need to find something quickly in a manual--that is, when you need to use a manual as a reference rather than as a tutorial. We urge you to learn these search commands as well. If you want to do that now, follow this cross reference to section 2.2 How to search Info documents for specific subjects.

Yet another set of commands are meant for experienced users; you can find them by looking in the Directory node for documentation on Info. Finding them will be a good exercise in using Info in the usual manner.

>> Type d to go to the Info directory node; then type
   mInfo and Return, to get to the node about Info and
   see what other help is available.

2.7 Tags Tables for Info Files

You can speed up the access to nodes of a large Info file by giving it a tags table. Unlike the tags table for a program, the tags table for an Info file lives inside the file itself and is used automatically whenever Info reads in the file.

To make a tags table, go to a node in the file using Emacs Info mode and type M-x Info-tagify. Then you must use C-x C-s to save the file. Info files produced by the makeinfo command that is part of the Texinfo package always have tags tables to begin with.

Once the Info file has a tags table, you must make certain it is up to date. If you edit an Info file directly (as opposed to editing its Texinfo source), and, as a result of deletion of text, any node moves back more than a thousand characters in the file from the position recorded in the tags table, Info will no longer be able to find that node. To update the tags table, use the Info-tagify command again.

An Info file tags table appears at the end of the file and looks like this:

^_^L
Tag Table:
File: info, Node: Cross-refs^?21419
File: info,  Node: Tags^?22145
^_
End Tag Table

Note that it contains one line per node, and this line contains the beginning of the node's header (ending just after the node name), a `DEL' character, and the character position in the file of the beginning of the node.

2.8 Checking an Info File

When creating an Info file, it is easy to forget the name of a node when you are making a pointer to it from another node. If you put in the wrong name for a node, this is not detected until someone tries to go through the pointer using Info. Verification of the Info file is an automatic process which checks all pointers to nodes and reports any pointers which are invalid. Every `Next', `Previous', and `Up' is checked, as is every menu item and every cross reference. In addition, any `Next' which does not have a `Previous' pointing back is reported. Only pointers within the file are checked, because checking pointers to other files would be terribly slow. But those are usually few.

To check an Info file, do M-x Info-validate while looking at any node of the file with Emacs Info mode.

2.9 Emacs Info-mode Variables

The following variables may modify the behavior of Info-mode in Emacs; you may wish to set one or several of these variables interactively, or in your `~/.emacs' init file. See section `Examining and Setting Variables' in The GNU Emacs Manual. The stand-alone Info reader program has its own set of variables, described in section `Manipulating Variables' in GNU Info.

Info-directory-list
The list of directories to search for Info files. Each element is a string (directory name) or nil (try default directory). If not initialized Info uses the environment variable @env{INFOPATH} to initialize it, or Info-default-directory-list if there is no @env{INFOPATH} variable in the environment. If you wish to customize the Info directory search list for both Emacs info and stand-alone Info, it is best to set the @env{INFOPATH} environment variable, since that applies to both programs.
Info-additional-directory-list
A list of additional directories to search for Info documentation files. These directories are not searched for merging the `dir' file.
Info-fontify
When set to a non-nil value, enables highlighting of Info files. The default is t. You can change how the highlighting looks by customizing the faces info-node, info-xref, info-header-xref, info-header-node, info-menu-5, info-menu-header, and info-title-n-face (where n is the level of the section, a number between 1 and 4). To customize a face, type M-x customize-face RET face RET, where face is one of the face names listed here.
Info-use-header-line
If non-nil, Emacs puts in the Info buffer a header line showing the `Next', `Prev', and `Up' links. A header line does not scroll with the rest of the buffer, making these links always visible.
Info-scroll-prefer-subnodes
If set to a non-nil value, SPC and BACKSPACE (or DEL) keys in a menu visit subnodes of the current node before scrolling to its end or beginning, respectively. For example, if the node's menu appears on the screen, the next SPC moves to a subnode indicated by the following menu item. Setting this option to nil results in behavior similar to the stand-alone Info reader program, which visits the first subnode from the menu only when you hit the end of the current node. The default is t.
Info-enable-active-nodes
When set to a non-nil value, allows Info to execute Lisp code associated with nodes. The Lisp code is executed when the node is selected. The Lisp code to be executed should follow the node delimiter (the `DEL' character) and an `execute: ' tag, like this:
^_execute: (message "This is an active node!")
Info-enable-edit
Set to nil, disables the `e' (Info-edit) command. A non-nil value enables it. See section 2.3 Adding a new node to Info.


Go to the first, previous, next, last section, table of contents.