24.4.7 HTML Cross Reference Link Preservation: manual-noderename.cnf

Occasionally changes in a program require removing (or renaming) nodes in the manual in order to have the best documentation. Given the nature of the web, however, links may exist anywhere to such a removed node (renaming appears the same as removal for this purpose), and it’s not ideal for those links to simply break.

Therefore, Texinfo provides a way for manual authors to specify old node names and the new nodes to which the old names should be redirected, via the file manual-noderename.cnf, where manual is the base name of the manual. For example, the manual texinfo.texi would be supplemented by a file texinfo-noderename.cnf. (This name can be overridden by setting the RENAMED_NODES_FILE customization variable; see Customization Variables).

The file is read in pairs of lines, as follows:

old-node-name
@@{} new-node-name

The usual conversion from Texinfo node names to HTML names is applied; see this entire section for details (see HTML Xref). The unusual ‘@@{}’ separator is used because it is not a valid Texinfo construct, so can’t appear in the node names.

The effect is that makeinfo generates a redirect from old-node-name to new-node-name when producing HTML output. Thus, external links to the old node are preserved.

Lines consisting only of whitespace are ignored. Comments are indicated with an ‘@c’ at the beginning of a line, optionally preceded by whitespace.

Another approach to preserving links to deleted or renamed nodes is to use anchors (see @anchor). There is no effective difference between the two approaches.