4.6 Cross-references

Includes docxref, ref, url and webref.

Writing a document, you frequently wish to refer to other parts of the same or other documents, or else to documents scattered around the web.

The cross-reference element you will use most often is the ref element, which refers to another part of the same document. It takes a required `id' attribute, giving the ID of the element you wish to refer to; any element with an ID attribute may be referred to. This will produce a named reference to the target element, based on the type and name of that element, and will make a link to it if the output format allows that. If the element has any content, this will be used as the link text; if it has no content, the link text will be generated, as something like `Section xxx'. For example, there is a link, above, to the ref element's documentation, which was specified in this document's source as <ref id=el.sun.ref>ref</ref>, but I could have written just <ref id=el.sun.ref/> to get Appendix C.1.57.

The docxref element refers to all or part of another Starlink document. To use this, you must declare an entity which refers to the document as follows:

<!DOCTYPE sun PUBLIC "-//Starlink//DTD Starlink SUN//EN" [
  ...
  <!ENTITY otherdoc 
    PUBLIC "-//Starlink//DOCUMENT Summary SUN/123//EN" SUBDOC>
  ...
]>

In future, the SGML kit will be set up so that this `formal public identifier' (FPI) will map to a summary document which will allow the SGML system to effectively query the target document. At present, however (release DR-0.7), it has been decided to distribute the kit with these document summaries missing, and so the down-converters have been written so that they fail gracefully and silently in this case, and generate a link to the Starlink documents available at RAL if the FPI is declared in this correct format. Jade will warn you about its inability to resolve the FPI, but this can be ignored. See Appendix E.2 for maintainer-level discussion of document summaries.

More straightforwardly, you can use the docxref element without declaring entities, by simply giving the document reference as the value of the `doc' attribute: <docxref doc='SUN/123'/>. In this case, the link is generated by the same basic algorithm as mentioned in the previous paragraph. This is less robust than using document summaries, but usually good enough.

When linking to other Starlink documents, you may only link to IDs which have been `exported' from the document; by the same mechanism, others may only link to IDs which you have exported from your document. You export an ID by giving the attribute `export' alongside the `id' attribute. To ensure that there is a rich field of targets for other documents (see also SUN/188: 3 ESTABLISHING CROSS-REFERENCES), most of the Starlink document types enforce a `link policy' (see the `EnforceLinkPolicy' feature in Section 4.1), requiring that all sect and subsect elements (at least) have both the `id' and `export' attributes present. Note that the export attribute must be explicitly present - it is not automatically inserted or assumed - even though it is redundant when it is mandatory. The `export' attribute is thus both an indication to the processing system that it may link to this element from outside, and an explicit warning to future maintainers of the document that they should not delete or change this ID.

The webref and url elements are straightforward: they both refer to a resource on the web. The webref element is much like HTML's a element, providing link text and a URL for the target; the url element quotes the URL directly.

As rather a special case, these cross-reference elements are allowable in the verbatim element, which is occasionally quite useful. For example, the contents of Figure 5 makes extensive use of this, to link from the element names to their documentation in Appendix D. This application uses the ref element's text attribute, and the result is that the link disappears in the paper version of the document. I don't imagine that the docxref element would often be useful here, but url and webref might be.