Make a cross-reference to another Starlink document. Example:
<!DOCTYPE sun PUBLIC "-//Starlink//DTD Starlink SUN//EN" [ <!ENTITY otherdoc PUBLIC "-//Starlink//DOCUMENT Summary SUN/123//EN" SUBDOC> ]> ... <p>See also <docxref doc=otherdoc />, particularly the <docxref doc=otherdoc loc=vimport>warning</docxref> notes there.
Exactly as with the ref element, you can give the element no content, in which case the generated text will be of the form `SUN/XXX', or `SUN/XXX: section nnn'. That is, the generated texts should be grammatically consistent with each other. Note, however, that this mechanism for generating text is intended to be a shorthand, with pretensions to no more than being correct most of the time; sometimes you will need to help it out.
This element is designed to work with summary documents, which express the structure of the target document, and list the valid potential targets; this design means that you can't accidentally refer to a document, or a section, which doesn't exist, only to have your links break later. There is a maintenance problem, however, in distributing accurate document summaries, which has been deemed awkward enough that no such summaries are being distributed in the initial version of the Starlink SGML kit.
Instead, you can simply rely on the kit's fallback method of
determining links for docxref elements.
If the public identifier supplied to the element is of the form of the
example above, so that the last word in the `description' part of the
public identifier is of the form XXX/NNN (for example,
SUN/123), then the document will make a link to the
corresponding document at the central Starlink document
server. If you also supply a `loc' attribute, the system
will add that to the end of the generated URL.
If you want to make linking within your document more robust, you
can generate document summaries yourself. Try experimenting with the
script in $STARLINK_SGML_DIR/lib/htx2summ.pl
to convert a current LaTeX-based Starlink document, and its HTX files,
into a document summary file. This should become easier, or even
automatic, in future.
attribution, cite, code, dt, em, entry, foreign, kbd, line, p, px, quote, span, strong, verbatim
( #pcdata
|
em |
strong |
quote |
code |
kbd |
cite |
m |
angle |
foreign) *
docxref |_(#PCDATA | |__em | |__strong | |__quote | |__code | |__kbd | |__cite | |__m | |__angle | |__foreign)*
At one time, the link text could be specified via the `text' attribute. This is now strongly deprecated in favour of specifying it via docxref element content, and this attribute is likely to disappear without further warning.
Indicates a location within a document. The value of the loc attribute is an ID reference within the target document.
Indicates the document we wish to link to. The value of this attribute is an entity (declared in the document declaration subset), which references another document.