This section describes the processes that occur when a set of hypertext documents is linked. It is intended to clarify the messages that appear and to give some background information to help solve problems and avoid inefficiencies.
When you invoke the hlink
command, it first looks to find all the documents that may
need to be linked. This it does by searching in all the document libraries specified on the
command line (or just the current directory by default), looking for directories with a “.htx”
extension.
It then ensures that each document has an up to date index file (a file called “htx.index” stored within the document directory), creating one if necessary. Index files are text files that contain, amongst other things, details of all the potential in-going and out-going cross-references for a document and list the HTML files in which they occur. This is a summary of the cross-links the document might potentially be involved in and serves to reduce the time needed to re-link it on subsequent occasions. New index files are normally only re-generated when a document changes.
In addition to cross-reference information, index files also contain details of the title of each HTML page in the document and an indication of which is the “top” page (see §3.3). This information is used by other HTX utilities to perform documentation searches, etc.
The linker identifies those documents that have changed since the library they reside in was last linked by looking for a file called “htx.log” which serves as a date-stamp in each document library (if this file is absent, all documents in the library are considered changed). The contents of the “htx.log” file also list the location of each local document when the library was last re-linked. Any that have moved to a different location are also regarded as “changed”.
The linker identifies all other documents which refer to any of the changed documents. Since all of these are potentially involved in cross-references that may no longer be valid, they will all need to be re-linked.
A further search is then made of the libraries that appear on the HTX_PATH
search path
(see §2.3). If any of the documents that needs re-linking refers to a document on this path,
then the latter document’s index file is searched to identify the HTML file that is being
referenced.
Finally, the affected HTML files are edited to insert the new, correct URLs. After this, any WWW browser should be able to follow any of the links between the documents and arrive at the correct location.
A document set will need linking again whenever a document is added or removed, or whenever one of its documents changes. However, because the linker can quickly identify which files are affected and can utilise existing index file information, subsequent linking operations are much faster.
When establishing a link between two local documents, the HTX linker has a choice of using an absolute file name for the target, or a relative one. The rule used is that relative cross-references are always generated if two documents reside in the same document library (i.e. the same directory), otherwise an absolute name is used.
This means that if a document library is moved, all cross-links between documents within it will remain intact. Only those from documents outside the library will fail and require re-linking.
In the interests of efficiency, the HTX linker is designed to generate references to locally-installed documentation whenever possible. If a referenced document cannot be found locally, however, it will instead generate a reference to a remote document server – which should have a complete set of documentation available. In this way, links to documents that are not available locally should not fail, and the reader should always see a complete set of documentation.
The linker regards a document as remote if it is referenced by one of the documents it is linking, but it
cannot find it either in the document libraries being linked or on the HTX_PATH
search path (see
§2.3).
Note that the HTX linker will not look up a document on a remote machine. All it does is to insert the remote server reference. References to invalid labels in remote documents (or, indeed, to non-existent documents) cannot therefore be detected at link time and diagnosing this type of error is the responsibility of the server itself.