Symbolic References between Living Documents

The method of the previous section to generated symbolic hyperized links can easily be extended to external documents processed by L^ATEX2HTML. When L^ATEX2HTML processes a document, it generates a Perl file named <prefix>labels.pl which contains a list of all the symbolic labels that were defined, along with their locations. The <prefix> is empty unless otherwise specified, to allow different document segments to share the same directory.

\externallabels

Links to an external document are then possible once a connection is established to that document's labels.pl file. This connection is established by the \externallabels command:

\externallabels{<URL to directory of external document>}
{<local copy of external document labels.pl file>}

The first argument to \externallabels should be a URL to the directory containing the external document. The second argument should be the full path-name to the labels.pl file belonging to the external document. Note that for remote external documents it is necessary to copy the labels.pl file locally so that it can be read when processing a local document that uses it. The command \externallabels can be used once for each external document in order to import the external labelsinto the current document. A warning is given if labels.pl cannot be found.

If a symbolic reference made in either of the commands described on the previous page is not defined within the document itself, L^ATEX2HTML will look for that reference in one of the external files¹¹. After any modifications in an external document (sections added/deleted, segmentation into different physical parts, etc.) a new labels.pl will be generated. If the \externallabels command in another document contains the correct address to an updated copy of the labels.pl file, then the cross-references will be re-aligned after running the local document through the translator.

There is also a mechanism analogous to the label-ref pairs of L^ATEX, which can be used only within a single document. These labels are called internal labels, as opposed to the external labels defined above. They are used extensively with the document segmentation strategy described later.

Either type of label is defined with a L^ATEX \label command. Labels can be referenced within a document using a \ref command. When processed by L^ATEX, each \ref command is replaced by the section number in which the corresponding \label occurred. When processed by the translator, each \ref is replaced by a hypertext link to the place where the corresponding \label occurred.

\externalref

This mechanism can be extended to external documents:

\externalref{<symbolic label in remote document>}

The argument to \externalref may be any symbolic label defined in the labels.pl file of any of the external documents. Such references to external symbolic labels are then translated into hyper-links pointing to the external document.

\externalcite

Analogous to \externalref, the \externalcite command is used to create a citation link, where the bibliography page is not part of the current document. As with \externalref symbolic labels for the bibliography page must have been loaded using \externallabels.

A particularly important use for this is in allowing multiple documents to access information in a common bibliographic listing. For example: all of an author's publications; a comprehensive listing of publications in a particular field; the (perhaps yearly) output of publications from a particular organisation or institution.

Thanks... to Uffe Engberg for suggesting this feature.

Footnotes

... files¹¹

Care must be taken to ensure that critical symbolic references are unique across related documents.