##
Symbolic References between Living Documents

Subsections

- - `\externallabels`
  - `\externalref`
  - `\externalcite`
- Cross-Referencing Example

The method of the previous section to generated symbolic hyperized links can easily be extended to external documents processed by LATEX2`HTML`. When LATEX2`HTML` 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 labels into 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, LATEX2`HTML` will look for that reference in one of the external files39. 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 LATEX, 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 LATEX `\label` command. Labels can be referenced within a document using a `\ref` command. When processed by LATEX, 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.