GNU Info

(texinfo)Pointer Validation

---

Next: makeinfo in Emacs Prev: makeinfo options Up: Creating an Info File

---

Enter node , (file) or (file)node

Pointer Validation
------------------

  If you do not suppress pointer validation with the `--no-validate'
option or the `@novalidate' command in the source file (*note Use TeX:
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.  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.