texinfo: HTML Xref Link Basics

HTML Xref

HTML Xref Node Name Expansion

Back to Software Index

24.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 (Note:
Cross References), and from "external information" (Note: HTML Xref
Configuration).

  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 filenames, is that base filenames
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 (Note: Other Customization
Variables), doing so would make cross-manual references to such nodes
invalid.

  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, however, is another bit
of the external information (Note: HTML Xref Configuration).  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.  Note: HTML Xref Mismatch.