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