Finding Badly Referenced Nodes

Next: Refilling Paragraphs  Prev: Using occur

You can use the Info-validate command to check whether any of the `Next', `Previous', `Up' or other node pointers fail to point to a node. This command checks that every node pointer points to an existing node. The Info-validate command works only on Info files, not on Texinfo files.

The makeinfo program validates pointers automatically, so you do not need to use the Info-validate command if you are using makeinfo. You only may need to use Info-validate if you are unable to run makeinfo and instead must create an Info file using texinfo-format-region or texinfo-format-buffer, or if you write an Info file from scratch.

Running Info-validate

To use Info-validate, visit the Info file you wish to check and type:

M-x Info-validate
(Note that the Info-validate command requires an upper case `I'. You may also need to create a tag table before running Info-validate. See Tagifying.)

If your file is valid, you will receive a message that says ``File appears valid''. However, if you have a pointer that does not point to a node, error messages will be displayed in a buffer called `*problems in info file*'.

For example, Info-validate was run on a test file that contained only the first node of this manual. One of the messages said:

In node "Overview", invalid Next: Texinfo Mode
This meant that the node called `Overview' had a `Next' pointer that did not point to anything (which was true in this case, since the test file had only one node in it).

Now suppose we add a node named `Texinfo Mode' to our test case but we do not specify a `Previous' for this node. Then we will get the following error message:

In node "Texinfo Mode", should have Previous: Overview
This is because every `Next' pointer should be matched by a `Previous' (in the node where the `Next' points) which points back.

Info-validate also checks that all menu entries and cross references point to actual nodes.

Note that Info-validate requires a tag table and does not work with files that have been split. (The texinfo-format-buffer command automatically splits large files.) In order to use Info-validate on a large file, you must run texinfo-format-buffer with an argument so that it does not split the Info file; and you must create a tag table for the unsplit file.

Creating an Unsplit File

You can run Info-validate only on a single Info file that has a tag table. The command will not work on the indirect subfiles that are generated when a master file is split. If you have a large file (longer than 70,000 bytes or so), you need to run the texinfo-format-buffer or makeinfo-buffer command in such a way that it does not create indirect subfiles. You will also need to create a tag table for the Info file. After you have done this, you can run Info-validate and look for badly referenced nodes.

The first step is to create an unsplit Info file. To prevent texinfo-format-buffer from splitting a Texinfo file into smaller Info files, give a prefix to the M-x texinfo-format-buffer command:

C-u M-x texinfo-format-buffer
or else

C-u C-c C-e C-b
When you do this, Texinfo will not split the file and will not create a tag table for it.

Tagifying a File

After creating an unsplit Info file, you must create a tag table for it. Visit the Info file you wish to tagify and type:

M-x Info-tagify
(Note the upper case `I' in Info-tagify.) This creates an Info file with a tag table that you can validate.

The third step is to validate the Info file:

M-x Info-validate
(Note the upper case `I' in Info-validate.) In brief, the steps are:

C-u M-x texinfo-format-buffer
M-x Info-tagify
M-x Info-validate
After you have validated the node structure, you can rerun texinfo-format-buffer in the normal way so it will construct a tag table and split the file automatically, or you can make the tag table and split the file manually.

Splitting a File Manually

You should split a large file or else let the texinfo-format-buffer or makeinfo-buffer command do it for you automatically. (Generally you will let one of the formatting commands do this job for you. See Create an Info File.)

The split-off files are called the indirect subfiles.

Info files are split to save memory. With smaller files, Emacs does not have make such a large buffer to hold the information.

If an Info file has more than 30 nodes, you should also make a tag table for it. See Using Info-validate, for information about creating a tag table. (Again, tag tables are usually created automatically by the formatting command; you only need to create a tag table yourself if you are doing the job manually. Most likely, you will do this for a large, unsplit file on which you have run Info-validate.)

Visit the Info file you wish to tagify and split and type the two commands:

M-x Info-tagify
M-x Info-split
(Note that the `I' in `Info' is upper case.)

When you use the Info-split command, the buffer is modified into a (small) Info file which lists the indirect subfiles. This file should be saved in place of the original visited file. The indirect subfiles are written in the same directory the original file is in, with names generated by appending `-' and a number to the original file name.

The primary file still functions as an Info file, but it contains just the tag table and a directory of subfiles.