3. Info for Experts

This chapter explains how to write an Info file by hand. 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.

The makeinfo command converts a Texinfo file into an Info file; texinfo-format-region and texinfo-format-buffer are XEmacs functions that do the same.

See (texinfo)Top section ‘Overview of Texinfo’ in Texinfo: The GNU Documentation Format, for how to write a Texinfo file.

See (texinfo)Creating an Info File section ‘Creating an Info File’ in Texinfo: The GNU Documentation Format, for how to create an Info file from a Texinfo file.

See (texinfo)Installing an Info File section ‘Installing an Info File’ in Texinfo: The GNU Documentation Format, for how to install an Info file after you have created one.

However, if you want to edit an Info file manually and install it manually, here is how.

3.1 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 Menu.

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.

3.2 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 on the node graph, 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.

3.3 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!

3.3.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.

3.4 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 XEmacs 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.

3.5 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 XEmacs Info mode.

This document was generated by Aidan Kehoe on December 27, 2016 using texi2html 1.82.