6 REMOTE DOCUMENT SERVERS

 6.1 Specifying a Document Server
 6.2 The Document Server’s Role

This section explains how a remote document server is specified and the role it performs.

6.1 Specifying a Document Server

If HTX detects that a document has been referenced but cannot find it locally (see §4.4), it will generate a reference to a remote document server in place of a link to the local document. The URL it generates in this case takes the form:

  $HTX_SERVER/docname.htx/some_file.html?xref_label

That is, it replaces any directory path at the start of the URL with the URL of a remote document server, obtained by translating the HTX_SERVER environment variable. It also replaces “#xref_” with “?xref_” so that the server will receive the label field of the URL as a query string which it can interpret.

You may set the HTX_SERVER environment variable to identify any document server you like (for instance, one that you write yourself). However, if you do not specify one explicitly, the default is to use the Starlink HTX document server at RAL, whose URL is:

  http://www.starlink.ac.uk/cgi-bin/htxserver

Once a document has been linked, the choice of server is fixed, until it is linked again.

6.2 The Document Server’s Role

It is the remote document server’s responsibility to interpret the URL it receives when the cross-reference is followed and, typically, to return the correct URL (or the document itself) to the browser. The server will therefore have to search for the document in whatever form it takes on the remote machine (it may not necessarily be in HTML format). This may involve similar steps to those that the HTX linker would have performed had the document been available locally (e.g. looking the reference up in an index file), except that they are performed at run-time rather than in advance when the document is linked. The server should also issue any necessary diagnostics – about invalid labels or documents that cannot be found, for example.