texinfo: HTML Xref Configuration

HTML Xref

HTML Xref Link Preservation

HTML Xref Mismatch

Back to Software Index

24.4.6 HTML Cross Reference Configuration: 'htmlxref.cnf'
---------------------------------------------------------

'makeinfo' reads a file named 'htmlxref.cnf' to gather information for
cross references to other manuals in HTML output.  It is looked for in
the following directories:

'./'
     (the current directory)

'./.texinfo/'
     (under the current directory)

'~/.texinfo/'
     (where '~' is the current user's home directory)

'SYSCONFDIR/texinfo/'
     (where SYSCONFDIR is the system configuration directory specified
     at compile-time, e.g., '/usr/local/etc')

'DATADIR/texinfo/'
     (likewise specified at compile time, e.g., '/usr/local/share')

  All files found are used, with earlier entries overriding later ones.
The Texinfo distribution includes a default file which handles many GNU
manuals; it is installed in the last of the above directories, i.e.,
'DATADIR/texinfo/htmlxref.cnf'.

  The file is line-oriented.  Lines consisting only of whitespace are
ignored.  Comments are indicated with a '#' at the beginning of a line,
optionally preceded by whitespace.  Since '#' can occur in urls (like
almost any character), it does not otherwise start a comment.

  Each non-blank non-comment line must be either a "variable assignment"
or "manual information".

  A variable assignment line looks like this:

     VARNAME = VARVALUE

  Whitespace around the '=' is optional and ignored.  The VARNAME should
consist of letters; case is significant.  The VARVALUE is an arbitrary
string, continuing to the end of the line.  Variables are then
referenced with '${VARNAME}'; variable references can occur in the
VARVALUE.

  A manual information line looks like this:

     MANUAL KEYWORD URLPREFIX

with MANUAL the short identifier for a manual, KEYWORD being one of:
'mono', 'node', 'section', 'chapter', and URLPREFIX described below.
Variable references can occur only in the URLPREFIX.  For example (used
in the canonical 'htmlxref.cnf'):

     G = http://www.gnu.org
     GS = ${G}/software
     hello mono    ${GS}/hello/manual/hello.html
     hello chapter ${GS}/hello/manual/html_chapter/
     hello section ${GS}/hello/manual/html_section/
     hello node    ${GS}/hello/manual/html_node/

  If the keyword is 'mono', URLPREFIX gives the host, directory, and
file name for MANUAL as one monolithic file.

  If the keyword is 'node', 'section', or 'chapter', URLPREFIX gives the
host and directory for MANUAL split into nodes, sections, or chapters,
respectively.

  When available, 'makeinfo' will use the "corresponding" value for
cross references between manuals.  That is, when generating monolithic
output ('--no-split'), the 'mono' url will be used, when generating
output that is split by node, the 'node' url will be used, etc.
However, if a manual is not available in that form, anything that is
available can be used.  Here is the search order for each style:

     node    => node,    section, chapter, mono
     section => section, chapter, node,    mono
     chapter => chapter, section, node,    mono
     mono    => mono,    chapter, section, node

  These section- and chapter-level cross-manual references can succeed
only when the target manual was created using '--node-files'; this is
the default for split output.

  If you have additions or corrections to the 'htmlxref.cnf' distributed
with Texinfo, please email <bug-texinfo@gnu.org> as usual.  You can get
the latest version from <http://ftpmirror.gnu.org/texinfo/htmlxref.cnf>.