21.1.4 Pointer Validation

If you do not suppress pointer validation with the ‘--no-validate’ option or the @novalidate command in the source file (see section Use TeX), makeinfo will check the validity of the final Info file. Mostly, this means ensuring that nodes you have referenced really exist. Here is a complete list of what is checked:

1. If a `Next', `Previous', or `Up' node reference is a reference to a node in the current file and is not an external reference such as to ‘(dir)’, then the referenced node must exist.
2. In every node, if the `Previous' node is different from the `Up' node, then the node pointed to by the `Previous' field must have a `Next' field which points back to this node.
3. Every node except the `Top' node must have an `Up' pointer.
4. The node referenced by an `Up' pointer must itself reference the current node through a menu item, unless the node referenced by `Up' has the form `(file)'.
5. If the `Next' reference of a node is not the same as the `Next' reference of the `Up' reference, then the node referenced by the `Next' pointer must have a `Previous' pointer that points back to the current node. This rule allows the last node in a section to point to the first node of the next chapter.
6. Every node except `Top' should be referenced by at least one other node, either via the `Previous' or `Next' links, or via a menu or a cross-reference.

Some Texinfo documents might fail during the validation phase because they use commands like @value and @definfoenclose in node definitions and cross-references inconsistently. (Your best bet is to avoid using @-commands in node names.) Consider the following example:

@set nodename Node 1

@node @value{nodename}, Node 2, Top, Top

This is node 1.

@node Node 2, , Node 1, Top

This is node 2.

Here, the node “Node 1” was referenced both verbatim and through @value.

By default, makeinfo fails such cases, because node names are not fully expanded until they are written to the output file. You should always try to reference nodes consistently; e.g., in the above example, the second @node line should have also used @value. However, if, for some reason, you must reference node names inconsistently, and makeinfo fails to validate the file, you can use the ‘--commands-in-node-names’ option to force makeinfo to perform the expensive expansion of all node names it finds in the document. This might considerably slow down the program, though; twofold increase in conversion time was measured for large documents such as the Jargon file.

The support for @-commands in @node directives is not general enough to be freely used. For example, if the example above redefined nodename somewhere in the document, makeinfo will fail to convert it, even if invoked with the ‘--commands-in-node-names’ option.

‘--commands-in-node-names’ has no effect if the ‘--no-validate’ option is given.