Previous: , Up: HTML Xref   [Contents][Index]


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

The preferred approach to preserving links to deleted or renamed nodes is to use anchors (see @anchor), as this works with all output formats, including Info. However, Texinfo provides an alternative method to do this for HTML output via a separate file which specifes old node names and the new nodes to which the old names should be redirected. This method is deprecated, and support for these files will be removed in future Texinfo releases. It is specific to HTML and supporting @-commands in node names in these files in practice complicates the implementation in texi2any.

The renamed nodes file is named 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 a ‘@c’ at the beginning of a line, optionally preceded by whitespace.


Previous: , Up: HTML Xref   [Contents][Index]