texi2any 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)
(under the current directory)
(where ~ is the current user’s home directory)
(where sysconfdir is the system configuration directory specified at compile-time, e.g., /usr/local/etc)
(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 HTMLXREF_MODE customization variable can be set to modify how the
files are found. For instance, if set to ‘none’, no external information
is used. HTMLXREF_FILE sets the file name to something else than
htmlxref.cnf. see HTML Customization Variables.
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, texi2any 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.