The HTX linker is equipped to detect when documents have changed and to decide when re-linking is necessary. However, it takes a pragmatic approach to this in order to keep linking time to a minimum. As a result, there are occasions on which it may report that no documents need to be re-linked when this is not, in fact, the case.
This section is intended to help you understand when you need to re-link your hypertext documents and how to tell the linker to do this for you.
A documentation set may need to be re-linked whenever any file in any of its documents changes, or when any document is added or removed, or moved to a new location. The HTX linker detects changed documents by observing the modification dates of the document “.htx” directories, the associated index files, and both the modification date and contents of the “htx.log” date-stamp file in each document library.
This process is effective, except that it is sometimes possible to modify an HTML file within a
document without changing the modification date on the “.htx” directory that contains it. This is
particularly likely if the HTML file resides in a sub-directory within the document. If such
modifications are carried out, a simple remedy is to use the UNIX touch command to update the
document’s “.htx” directory and record the change before running the linker.
As an alternative, the hlink command may be invoked with the -d flag to specify a deep dependency
test of all document files. This causes it to check the modification dates of all the HTML files in all the
documents in order to detect changes. This is a thorough way of detecting changes, but may be rather
too slow for regular use on large document collections.
You should also remember that re-linking can be rendered necessary not only by changes in document
contents, but also by changes in document location. Thus, if documents or libraries are moved, it is
always wise to re-run hlink.
There are several ways to force a re-link of a document or library.
To re-link a particular document, or set of documents, from scratch, their index files may simply be removed, using a command such as:
The linker will then re-generate these indices and consider the affected documents to have changed.
They, and all other documents that refer to them, will then be re-linked as necessary. Alternatively, to
re-link all documents from scratch in this way, the -a flag may be given on the hlink command
line.
Removing the “htx.log” date-stamp file from a document library will also force the documents in that library to be re-linked but without unnecessarily re-generating any of its index files. This can be somewhat faster if the index files are known to be up to date.
It is often convenient to use the hlink command as part of software-maintenance procedures, such as
in makefiles, since this allows your documentation set to be re-linked automatically whenever
software is installed or de-installed. However, in a large software installation this can take some time.
Rather than re-linking after each item of software is changed, it can sometimes be more efficient to
wait until a sequence of changes has been completed. A grand re-link of the entire documentation set
can then be performed.
To permit this, you can set the HTX_NOLINK environment variable (to any value). While this variable is
set, the hlink command will cease to function normally. Instead. it will simply produce a message
saying that hypertext linking has been suppressed. You can then perform your software updates
without waiting for re-linking to occur. When you have finished, you can un-set the HTX_NOLINK
environment variable and use hlink to bring the cross-references in the associated documentation up
to date.