<xref>
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.
Content models
See appendix for information about this element in OASIS document type shells.
Inheritance
- topic/xref
Examples
- This example shows a cross-reference to another topic; that topic's title
will typically be used as the link
text.
<p>Background information about DITA is provided in the topic entitled <xref href="whatsdita.dita"></xref>.</p>
- The same cross reference could be created using @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>
- This example shows cross-references to another topic; the supplied text will
be used as the link
text:
<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>
- If you are linking to an element inside of a topic, use the following format
in the @href attribute:
filename.dita#topicid/elementid
- The @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
- If you are linking within the same file, you can leave off the file name
portion
filename.dita. So, for a section with the ID "mysection", use:#topicid/mysection
- Alternatively, if the link is to an element
within the same topic you can use:
#./mysection
- For a list item within that section, assuming the item has an ID of
"mylist", use:
#topicid/mylist
- Alternatively, because the link is to an
element within the same topic, you can use:
#./mylist
See DITA addressing for details on using URI references and Indirect key-based addressing for details on using key references.
If your URL has an ampersand (&) in it, you need to code that using a entity reference. For example, this URL includes an & character:
http://www.example.com/docview.wss?rs=757&context=SSVNX5
When used in an @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>
Attributes
The following attributes are available on this element: Universal attribute group, Link relationship attribute group, @outputclass, and @keyref.