<xref>
Use the <xref>
element to provide an inline cross reference. It is
commonly used to link to a different location within the current topic, a different topic,
a specific location in another topic, or an external resource. The target of the
cross-reference is specified using the @href
or @keyref
attributes.
When creating a cross-reference, link to the element structure, not the
<title>
element of the object. For example, to create a cross-reference to a
figure, link to the <fig>
element, not the <title>
element within the <fig>
element. Output processing determines whether the text of the <title>
element is used to render
the cross-reference.
Cross references that link to elements in other topics can employ key-based addressing by
using the @keyref
attribute. This enables the cross-reference to point to different
topics in the context of different top-level maps. Cross references that employ direct URI-based
addressing using the @href
attribute create dependencies; if the topic with the
cross-reference is included in a map, the target topic also might need to
be included for the cross-reference to be resolvable in the context of that map. While you can
use conditional processing to have different cross-references for different contexts, it is usually
easier and more effective to use keys. By using keys, the cross-reference can be independent of the
contexts it might be used in, because it is up to each different map to bind the key used by the
cross-reference to the appropriate target.
In many cases it is best to avoid inline cross references in favor of links of links that are generated by the related-links element or relationship tables. Such links typically are rendered at the end of the topic. This prevents readers from leaving a topic and missing important information. Using relationship tables also enables the links to be managed at a DITA map level, making it possible for topics to be quickly integrated into new contexts without breaking links.
See appendix for information about this element in OASIS document type shells.
- topic/xref
<p>Background information about DITA is provided in the topic entitled
<xref href="whatsdita.dita"></xref>.</p>
@keyref
instead of @href
; using @keyref
allows the
link to be redirected to different resources when used in different map
contexts.<p>Background information about DITA is provided in the topic entitled
<xref keyref="whatisdita"></xref>.</p>
<p><xref href="whatsdita.dita#tmmdita">Background information about
DITA</xref> is provided free of charge. For a context free cross reference,
the keyref attribute can also link to a topic for <xref keyref="whatisdita">information
about DITA</xref>.</p>
@href
attribute: filename.dita#topicid/elementid
@keyref
attribute can
also be used to link to an element inside of a topic; in this case the key
represents the topic, but the element ID remains the same:
keyname/elementid
#topicid/mysection
#./mysection
#topicid/mylist
#./mylist
See DITA addressing for details on using URI references and Indirect key-based addressing for details on using key references.
http://www.example.com/docview.wss?rs=757&context=SSVNX5
@href
attribute, the ampersand must be entered as
& as shown
here:<xref href="http://www.example.com/docview.wss?rs=757&context=SSVNX5"
scope="external">Part number SSVNX5</xref>
The following attributes are
available on this element: Universal attribute group,
Link relationship attribute group, outputclass, and @keyref
.