This section describes how you should organise your hypertext documentation to make use of HTX to maintain and use cross-references between documents.
HTX assumes that each hypertext document resides beneath a top-level directory and it recognises these document directories from their extension, which should always be “.htx”. When it needs to locate the contents of a document, it will search inside document directories (to any required depth) looking for files with an extension of “.html” which contain the hypertext itself, in HTML format.
The first step in organising your hypertext documentation should therefore be to collect all the HTML files comprising each document together into a directory (or directory tree) and to give the (top level) directory a distinctive name such as:
The “design-study” part of this is the document name by which it will be known to other authors, and the “.htx” part identifies it to HTX as a candidate for the various operations it performs. Once you have made a document available to other people, you should not subsequently change its name, even if you move it somewhere else, because other documents may be referring to it and will still know it by its original name.
Because it is concerned with collections of hypertext documents, HTX uses the concept of a document library. There is nothing particularly grand about this. It is simply a directory in which you store a collection of documents. You can call it whatever you like and populate it with the “.htx” directories for each of the documents in your collection. It is also a convenient place to keep other files related to the documentation set, perhaps even versions of the same documents in other formats.
The key thing about a document library is that it defines a place in which to look for documents. When you link a set of documents together (the term used for establishing the correct cross-references), HTX identifies the documents involved by searching in the document libraries you specify, looking for all the “.htx” directories they contain. By default, it will simply look in your current directory.
You may not always want to modify the contents of existing libraries, even although you may be referring to their documents. For example, you may have an established set of documentation in one or more libraries and be developing a new document that will eventually form part of that set. Your new document will probably need to refer to the others while you are working on it, but you may not want to (or have permission to) modify any of the existing documents.
In this case, you can specify a search path, on which HTX will look for other documents to which you
may be referring, but it will not attempt to link (i.e. modify) those other documents. The search path is
specified as a colon-separated list of directories via the HTX_PATH environment variable, for
instance:
This search path is used by all HTX commands when they need to find documents for which no
explicit location has been given. Note that if two documents with the same name occur at different
points on your HTX_PATH, only the first one will be used.
You can set HTX_PATH to search anywhere you like, but if you do not specify it yourself, it defaults
to:
where INSTALL in turn defaults to $HOME/star and STARLINK defaults to /star. The values of
these environment variables are evaluated when the HTX software is installed (not when
you later make use of it). By default, therefore, HTX will search for the standard set of
Starlink documents and on-line hypertext help, plus any others you may have installed
locally under your own user name (in the location identified by the INSTALL environment
variable).