texinfo: HTML Xref Link Preservation

HTML Xref

HTML Xref Configuration

Back to Software Index

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.txi' would be
supplemented by a file 'texinfo-noderename'.cnf.  (This name can be
overridden by setting the 'RENAMED_NODES_FILE' customization variable;
Note: 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 (Note: 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 (Note: @anchor).  There is no effective difference between
the two approaches.