21.4.1 HTML Cross-reference Link Basics

For our purposes, an HTML link consists of four components: a host name, a directory part, a file part, and a target part. We always assume the http protocol. For example:

http://host/dir/file.html#target

The information to construct a link comes from the node name and manual name in the cross-reference command in the Texinfo source (see Cross-references), and from external information (see HTML Cross-reference Configuration: htmlxref.cnf).

We now consider each part in turn.

The host is hardwired to be the local host. This could either be the literal string ‘localhost’, or, according to the rules for HTML links, the ‘http://localhost/’ could be omitted entirely.

The dir and file parts are more complicated, and depend on the relative split/mono nature of both the manual being processed and the manual that the cross-reference refers to. The underlying idea is that there is one directory for Texinfo manuals in HTML, and a given manual is either available as a monolithic file manual.html, or a split subdirectory manual/*.html. Here are the cases:

• If the present manual is split, and the referent manual is also split, the directory is ‘../referent/’ and the file is the expanded node name (described later).
• If the present manual is split, and the referent manual is mono, the directory is ‘../’ and the file is referent.html.
• If the present manual is mono, and the referent manual is split, the directory is referent/ and the file is the expanded node name.
• If the present manual is mono, and the referent manual is also mono, the directory is ./ (or just the empty string), and the file is referent.html.

Another rule, that only holds for file names, is that base file names are truncated to 245 characters, to allow for an extension to be appended and still comply with the 255-character limit which is common to many filesystems. Although technically this can be changed with the BASEFILENAME_LENGTH customization variable (see Other Customization Variables), doing so would make cross-manual references to such nodes invalid.

Any directory part in the file name argument of the source cross reference command is ignored. Thus, @xref{,,,../foo} and @xref{,,,foo} both use ‘foo’ as the manual name. This is because any such attempted hardwiring of the directory is very unlikely to be useful for both Info and HTML output.

Finally, the target part is always the expanded node name.

Whether the present manual is split or mono is determined by user option; makeinfo defaults to split, with the --no-split option overriding this.

Whether the referent manual is split or mono, however, is another bit of the external information (see HTML Cross-reference Configuration: htmlxref.cnf). By default, makeinfo uses the same form of the referent manual as the present manual.

Thus, there can be a mismatch between the format of the referent manual that the generating software assumes, and the format it’s actually present in. See HTML Cross-reference Mismatch.