3 ESTABLISHING CROSS-REFERENCES

 3.1 Exporting Cross-Reference Targets
 3.2 Referring to Cross-Reference Targets
 3.3 Referring to an Entire Document
 3.4 Linking your Hypertext Documents
 3.5 Using Cross-References from LATEX

Before you can establish cross-references between documents using HTX, you must export labelled targets for the cross-references to point at from each of the referenced documents. You must also enter links to implement the cross-references themselves. Both of these make use of standard HTML anchors, but in a special form that makes them recognisable to HTX.

3.1 Exporting Cross-Reference Targets

If one document is to cross-reference another, the referenced document should export a label that the other one can refer to. The position of this label identifies the point in the referenced document to which a reader should be transferred when the cross-reference is followed. If you understand HTML, you will be familiar with this idea, as it uses an HTML destination anchor for this purpose. For use with HTX, this should have a form such as:2

  <A NAME="xref_conclusions">any text</A>

In plain HTML, this makes “any text” a potential destination for a hypertext link, to which any other piece of HTML may refer.

What makes this anchor special to HTX is the “xref_” prefix given to the value of the NAME parameter. HTX recognises anchors with this form as potential targets for document cross-references, and this distinguishes HTX targets from other HTML destination anchors. This is important, because it gives the document’s author control over which points in the document other authors may reference.

Normally, many HTML destination anchors will be used for internal navigation within a document. When the document is revised, these may be subject to change, so they should not normally be referred to by other documents. However, destination anchors with the “xref_” prefix can be chosen carefully (and named appropriately) to identify stable components of a document, to which enduring references can be made from other documents. The author is, in effect, exporting a set of labels that tell other authors which parts of his document it is safe to refer to.

We will refer to an anchor with the form above as a cross-reference target and the characters that follow “xref_” as its label (“conclusions” in the example above). As in normal HTML, HTX labels are case sensitive. Unlike plain HTML, however, they must be unique within an entire hypertext document, not just within a single HTML file.

3.2 Referring to Cross-Reference Targets

To establish a cross-reference to another document you again use an HTML anchor, this time with the HREF parameter, in a form similar to the following:3

  <A HREF="/star/docs/sun188.htx/node33.html#xref_appendix">any text</A>

This is, of course, the standard HTML method of forming a hypertext link to another location identified by the Uniform Resource Locator (URL) given between double quotes. If this URL is correct (i.e. fully identifies the HTML file you want to reference), then this anchor will work as it stands, without any intervention from HTX.

What makes this link special to HTX is the particular form that the URL takes. Anchors containing such URLs are recognised by HTX and can then be repaired when the cross-reference target changes, by appropriately editing new values into the fields that are no longer valid. The key components of the URL that HTX recognises are:

  /sun188.htx/

which identifies the name of the document being referenced (in this case “sun188”, i.e. this document), and:

  #xref_appendix

where “#xref_” is a flag that identifies this as an HTX cross-reference and “appendix” is the cross-reference label in the target document that identifies which part of that document is being referenced. Note that HTX will only allow you to refer to cross-reference labels that have been exported by the target document and will warn you if you use an invalid label.

Because HTX can repair URL fields that are wrong, it is quite acceptable to omit everything inessential and to strip the URL down to just:

  <A HREF="/sun109.htx/#xref_conclusions">any text</A>

However, entering a full URL (or at least a guess at it) is often a good idea to start with, as it means the cross-reference may still work even if someone forgets to link your document.

3.3 Referring to an Entire Document

HTX recognises a cross-reference target with the form:

  <A NAME="xref_">any text</A>

(i.e. with a blank label) as a special case, to be used to identify the “top” page of a hypertext document. This should be the point to which a reader is transferred if the entire document is requested and no particular part of it is specified.

Any other document can refer to this label, using an anchor with the form:

  <A HREF="/any_where/docname.htx/any_file.html#xref_">any text</A>

but its inclusion as a cross-reference target in the referenced document is optional. If it is omitted, HTX will assume that the top HTML page in a document is named after the document itself. That is, it will use a URL such as:

  /some_where/docname.htx/docname.html#xref_

If your document does not follow this convention, then you should include a cross-reference target with a blank label at the start of whichever HTML file serves the same purpose.

3.4 Linking your Hypertext Documents

Once you have set up a collection of documents with cross-references implemented using the special forms of HTML anchor recognised by HTX, the next step is to link these documents together. This consists of editing the URLs in HTX cross-references so that they identify the current true location of the referenced files. No other URLs are touched during this process.

Linking hypertext documents is straightforward. Simply go to the directory containing the document collection (the document library) and use the command:

hlink

WARNING: this will modify your documents. If you are worried about this, then make a backup first.

The hlink command will display some informational messages as it links your documents and will warn you if you have referred to any cross-reference labels that do not exist. When it completes, you should be able to read your documents using any WWW browser and to follow all the cross-references that they contain.

When you change any of your documents, you can re-link them to accommodate the changes simply by using the hlink command again. Because no essential information is discarded during linking, this process can be repeated indefinitely. You do not need a fresh copy of the documents each time.

If the documents you want to link reside in more than one document library, then simply list the library directories on the command line, as follows:

  hlink dir1 dir2 dir3

Remember that any other local documents that you refer to (but do not actually want to modify) should reside in libraries that appear on your HTX_PATH search path (see §2.3). If they do not, they will be regarded as remote documents and the URLs generated for them will invoke a remote document server (see §4.4 and §6). This is usually less efficient than referring directly to local files.

3.5 Using Cross-References from LATEX

It is quite straightforward to insert HTX cross-reference anchors in HTML form directly into documents when writing them by hand. However, many substantial documents already exist in LATEX format and can be converted relatively easily into hypertext by using the LaTeX2HTML4 converter (see SUN/201). LATEX is, in any case, a convenient format for the primary source of many documents.

A facility is therefore available for generating HTX cross-references from commands within LATEX documents. The LATEX commands involved are normally ignored, but are detected by the star2html command that provides Starlink additions to the standard LaTeX2HTML. To allow these commands to work, the appropriate document preamble must also be included. The procedure to follow is described in SUN/199, but an outline of the principles involved is also given here.

To export an HTX cross-reference label from a LATEX document that is to be converted into hypertext, the following would be used:

  \xlabel{label}

which results in the HTML anchor:

  <A NAME=xref_label>?</A>

where “?” is some invisible character that simply serves to mark the position to which links should point. Note that the name of the label chosen should be unique within a LATEX document and must only contain alphanumeric characters (or be blank – see §3.3).

To insert a cross-reference to the target above into another document, you would use:

  \xref{any text}{docname}{label}

which results in the HTML anchor:

  <A HREF="http://www.starlink.ac.uk/cgi-bin/htxserver/docname.html?xref_label">any text</A>

This contains an initial guess at the required URL (a document stored on the RAL service), which will be recognised and modified as necessary (see §3.2) when the document is linked.

2Any other HTML anchor parameters may also be present and the double quotes are optional if the enclosed characters are all alphanumeric.

3Again, any other HTML anchor parameters may also be present.

4http://cbl.leeds.ac.uk/nikos/tex2html/doc/latex2html/latex2html.html