5 WHEN TO RE-LINK

 5.1 Accommodating Normal Document Changes
 5.2 Forcing a Re-Link
 5.3 Suppressing Re-Linking

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.

5.1 Accommodating Normal Document Changes

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.

5.2 Forcing a Re-Link

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:

  rm *.htx/htx.index

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.

5.3 Suppressing Re-Linking

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.