The system generates cross-references to other Starlink documents without further editing. It does not test that the HTML target exists, but assumes that if the document summary files exist, then the HTML targets exist, or will exist by the time the output documentation is installed. An alternative system would have the link targets refer to a live document server, so that the targets would be resolved when they are referenced, rather than when the document is processed. This would, however, be unnecessarily complicated for a first version of the system, as well as going beyond the current, and adequate, HTX model.
The current SGML set uses Star2html and HTX. Star2html (see SUN/199) generates a distributable document set with correct internal cross-references, and `best guess', but possibly broken, external ones. These references are then patched up in a separate installation phase, being edited by a copy of HTX primed with appropriate local knowledge (see SUN/188: 4 HOW HTX LINKING WORKS).
The aim of the current set is to produce documents which are in their final form, and can be moved to their final location without further editing - this assumes that documents are distributed in (SGML) source form and processed at installation time, and that the SGML set is the only system producing documentation. This aim has been achieved in the current version, but could benefit from more convenient parameterisation.
Since HTX is likely to remain in use for the forseeable future, the current set is intended to be used with HTX, and is claimed to be compatible with it. It produces links in the format recognised by HTX, as described (or defined?) in SUN/188: 3.2 Referring to Cross-Reference Targets. Note two points, however.
urlpath attribute in its
section and label elements which specifies the tail of the URL where a
particular section lives, relative to an (unspecified) document
server. The abstract-star2html.pl script includes a
--prefix option to control the start of this attribute,
and this option is used when this script is invoked during the
installation stage of the package makefile, so that the urlpath
attribute starts with the string sunNNN.htx/ (as
appropriate), ready to be recognised by HTX. This separation may seem
complicated, but it separates, as much as possible, features which are
internal to the system (internal labels and generated HTML filenames)
from features which are properly external (URL paths and locations in
a filesystem), using the document-summary files and the script used to
generate them as the interface.