22.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.php#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 section Cross References), and from external information, which is currently simply hardwired. In the future, it may come from an external data file.

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

One exception: the algorithm for node name expansion prefixes the string ‘g_t’ when the node name begins with a non-letter. This kludge (due to XHTML rules) is not necessary for filenames, and is therefore omitted.

Any directory part in the filename 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 is another bit of the external information. For now, makeinfo simply assumes the referent manual is the same as the present manual.

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 section HTML Cross-reference Mismatch.