1 INTRODUCTION

1.1 What Does HTX Do?

HTX is a set of utilities that allows you to maintain and access a collection of dynamic multi-page hypertext documents that refer to each other. Its main element is a hypertext linker which can be used to establish cross-references between documents and to re-establish these whenever changes occur to individual documents.

The information generated by the linking process is used by other HTX utilities to provide access to hypertext documentation, permitting document searches and the rapid display of selected parts of documents.

Other software can also make use of these facilities to obtain random access to any part of a cross-linked documentation set, forming a basis for on-line or context-sensitive hypertext help systems.

See §A for descriptions of each of the utilities that HTX provides.

1.2 What is a Hypertext Document?

The documents that HTX is concerned with are written using the Hypertext Markup Language (HTML)¹.

Of course, any page of hypertext written using HTML could be considered a document in its own right. However, most documents of substance will consist of multiple pages of HTML, joined together using hypertext links. It is convenient to gather these related pages together and to consider them as a single multi-page hypertext document. This is the sense in which the term document is used here.

1.3 Why are Cross-References a Problem?

The hyper-links that join different HTML pages within hypertext documents are normally defined by the document’s author. These are an internal matter – if the document structure changes, the author can change the internal links accordingly. If proper use is made of relative file names in establishing these links, it should also be possible to transport these documents as a whole to a different location without damaging the internal links.

HTX addresses the different problem of maintaining a collection of dynamic hypertext documents (probably written by many different authors) that have cross-references established between them. That is, each document may contain hyper-links to the contents of any other document in the collection.

In this situation, document locations may often need to change, and revision of individual documents will also result in the referenced material moving around within them. Since the links that implement HTML cross-references consist, essentially, of file names, they cannot survive this process and will rapidly end up pointing to the wrong places unless remedial action is taken.

In a large document collection, re-organising all necessary cross-references following every document change is not a task to contemplate doing by hand. Establishing and repairing these links is therefore a job for the HTX hypertext linker.

1.4 Mixing Local and Remote Documents

The inherent fragility of hypertext links is a problem faced by any project that needs to maintain a collection of related documents in hypertext form. The documentation for software projects typifies this. However, software documentation also suffers from an additional problem because it is usually distributed and installed along with the particular items of software it describes. This means that any sub-set of the complete documentation set must also be viable in its own right.

To give an example, a particular site may only have installed one or two items out of a complete collection of software, and so may only have a couple of documents that relate to the installed software available locally. This means that many of the cross-references that these documents make will be to other documents that do not exist on the local system. Ideally, these links should not simply fail.

The problem can be solved by using a document server to provide access to the missing documents from a central archive, where a copy of all the documents is maintained. A reader with any of the documents installed locally will then potentially have easy access to the entire documentation set, albeit with some time penalty when accessing non-local documents. One of the functions that HTX performs, therefore, is to generate appropriate requests for remote documents for processing by a central document server (see §4.4 §6).