This chapter describes various advanced Info commands, and 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 both to generate an Info file and to make a printed manual. See section `Overview of Texinfo' in Texinfo: The GNU Documentation Format.)
g, s, 1, -- 9, and e
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 (its directory node). gExpertRET would come back here.
Unlike m, g does not allow the use of abbreviations.
To go to a node in another file, you can include the filename 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 node `Top' in the file `dir'.
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.
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 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).
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.
If you grudge the system each character of type-in it requires, you might like to use the commands 1, 2, 3, 4, ... 9. They are short for the m command together with an argument. 1 goes through the first item in the current node's menu; 2 goes through the second item, etc.
If your display supports multiple fonts, and you are using Emacs' Info mode to read Info files, the `*' for the fifth menu item is underlined, and so is the `*' for the ninth item; these underlines make it easy to see at a glance which number to use for an item.
On ordinary terminals, you won't have underlining. If you need to actually count items, it is better to use m instead, and specify the name.
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.
To add a new topic to the list in the Info directory, you must:
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 from them. However, if you want to edit an Info file, 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, or the end of file. Note: If you put in a ^L to end a new node, be sure that there is a ^_ after it to start the next one, since ^L cannot start a node. Also, a nicer way to make a node boundary be a page boundary as well is to put a ^L right after the ^_.
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 `Top', which points at all the documentation for Info. The `Next' node is `Menus'.
The keywords Node, Previous, Up, and Next, 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 Info file directory 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)'. 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 filename, since Info when searching for a node does not expect one 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.
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--the argument that the user must give to the m command 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 on that file directory, but they do not have to; and files on 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.
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.)
They are just examples. The places they "lead to" do not really exist!
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.
Once the Info file has a tags table, you must make certain it is up
to date. If, 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:
^_ 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 Delete character, and the character position in the file of the beginning of the node.
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.
The following variables may modify the behaviour 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.
Info-enable-edit
nil, disables the `e' (Info-edit) command. A
non-nil value enables it. See section Adding a new node to Info.
Info-enable-active-nodes
nil value, allows Info to execute Lisp code
associated with nodes. The Lisp code is executed when the node is
selected.
Info-directory-list
nil (try default directory).
Info-directory
Info-directory is called.