When referring to an external Starlink document via a
docxref element, the processing system must
generate both the link text and, in the case of the HTML stylesheet,
the URL which is the link target. It does this by processing the
document referred to by the element's `doc' attribute. This document
must be marked up using the `document summary' DTD,
"-//Starlink//DTD Document Summary 0.1//EN".
The Document Summary DTD has the same general structure as the Starlink General one, but the only text in it is the abstract (possibly) and the content of the various section headings. The SGML set uses the structure expressed in here, to work out the section number which will be given to the link text. The DTD has attributes to control a `link policy' (whether we may link to all elements, or only those with the export attribute present), and exercise some control over the URLs which will be used in HTML targets, if these are not to be generated using the same algorithm used for the main document. There is more flexibility in the Document Summary DTD than is used at present. The DTD is well-commented, and you should refer to it for further details.
Since the Starlink General DTD declares itself as a client of the
Document Summary DTD (see Appendix E.1.2 for a discussion
of architectures), the processing of cross-referenced documents could
be done by having the `doc' attribute point to the main SGML source of
the target document and extracting the DocumentSummary architectural
instance. DSSSL's (sgml-parse) function does not, however,
support the extraction of architectural instances. There is a Jade
patch at Isogen which
adds this as a Jade extension; this has been incorporated into the
OpenJade distribution (see Appendix E.1.3.1), but not (yet)
into the Starlink version of Jade which accompanies this
set. Note, however, that this is almost entirely an implementation
issue: if this feature were to be added to Jade, as it might be if it
conforms to any updated DSSSL standard which includes this feature,
the only changes necessary would be a possible adjustment of that
element's HyTime declaration, some adjustment of the call of the
relevant (sgml-parse) function, and corresponding changes in
the package's installation script so that the document summary
catalogue points to the original documents rather than a
freshly-generated set of summaries. There would be no need for
documentation updates, since there would be no user-visible changes.
It is possible to extract the DocumentSummary architectural instance
by hand, using the command sgmlnorm -A documentsummary
ssn70.sgml for example.