xref

Use the cross-reference (<xref>) element to link to a different location within the current topic, or a different topic within the same help system, or to external sources, such as Web pages, or to a location in another topic. The href attribute on the <xref> element provides the location of the target.

Typically it is best to restrict yourself to linking to reference topics where the content of the target is clear from the <xref>'s text, for example API names and their descriptions. With other information types, it may be less clear to the user whether they should follow the link, and often they will, thereby missing important information in following paragraphs. Therefore it is a good idea to use links at the end of the topic, in the <related-links> element, wherever possible, rather than linking from within body content using <xref>. Links at the end of a topic can also be managed from outside the topic, using DITA maps: this allows topics to be quickly integrated into new contexts without breaking links.

Contains

( text data or ph or codeph or synph or filepath or msgph or userinput or systemoutput or b or u or i or tt or sup or sub or uicontrol or menucascade or term or q or boolean or state or keyword or option or parmname or apiname or cmdname or msgnum or varname or wintitle or tm or image or desc) (any number)

Contained by

section, example, desc, p, note, lq, q, sli, li, itemgroup, dt, dd, figgroup, pre, lines, ph, stentry, draft-comment, fn, linkinfo, entry, prereq, context, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, refsyn, proptypehd, propvaluehd, propdeschd, proptype, propvalue, propdesc, screen, b, u, i, tt, sup, sub, codeph, codeblock, pt, pd, synnote, area

Inheritance

topic/xref

Attributes

Name	Description	Data Type	Default Value	Required?
href	A hyperlink to an external Web page (URL) or other non-DITA resource, to another DITA topic in the same file or in another file, or to a specific element inside a DITA topic. The format attribute identifies the format of the target. Non-DITA targets use standard URL syntax. DITA content is targetted as follows: Target elsewhere in the same file: href="#topicID" href="#topicID/elemID Target in a different file: href="filename.dita#topicID" href="fname.dita#topicID/elemID" Elements inside a topic need to have their location scoped by the containing topic's ID. Only the id of the target element and the topic that contains it matter: id's on any other containing elements (for example an id on the <body> element) are not part of the link syntax. If the URL contains an ampersand character, the ampersand symbol (&) should be used to indicate that character	CDATA	#IMPLIED	No
keyref	Currently not implemented in DITA processors. Provides a key that a process can use to look up associated information.	NMTOKEN	#IMPLIED	No
type	Describes the target of a cross-reference and may generate cross-reference text based on that description. Only the <xref> element can link to content below the topic level: other types of linking can target whole topics, but not parts of topics. Typically <xref> should also be limited to topic-level targets, unless the output is primarily print-oriented. Web-based referencing works best at the level of whole topics, rather than anchor locations within topics. When targetting DITA content, the type should match one of the values in the target's class attribute. For example, if type="topic", the link could be to a generic topic, or any specialization of topic, including concept, task, and reference. Some possible values include: fig Indicates a link to a figure. table Indicates a link to a table. li Indicates a link to an ordered list item. fn Indicates a link to a footnote. section "section" indicates a link to a section. concept, task, reference, topic Cross-reference to a topic type. (no value) Defaults to generic topic, or the processor may retrieve the actual type from the target if available. Other values can be used to indicate other types of topics or elements as targets. Processing is only required to support the above list, or specializations of types in that list. Supporting additional types as targets may require the creation of processing overrides.	CDATA	#IMPLIED (Processed as if the target were of type "topic.")	No
%univ-atts; (%select-atts;, %id-atts;, translate, xml:lang)	A set of related attributes, described at %univ-atts;	parameter entity	PE not applicable	Not applicable
format	The format attribute identifies the format of the resource being cross referenced. The default format is "dita". Possible values include: dita The destination uses DITA topic markup, or markup specialized from a DITA topic. Unless otherwise specified, the corresponding default type will be treated as "topic." html The format of the linked-to resource is HTML or XHTML. pdf The format of the linked-to resource is PDF (opens a new window). ditamap The linked-to resource is a DITA map. It represents a referenced hierarchy at a position within referencing hierarchy, and a referenced relationship table included outside the referencing hierarchy (no value) Defaults to "dita" For other formats, you can use the file extension without the "." (for example, in a link to file "readme.txt", use "txt" as the value)	CDATA	#IMPLIED	No
scope	The scope attribute identifies the closeness of the relationship between the current document and the target resource. Set scope to `local` when the resource is part of the current set of content, and should be accessed and copied to the output directory. Set scope to `peer` when the resource is part of the current set of content but is not accessible at build time. Set scope to `external` when the resource is not part of the current information set and should open in a new browser window. The default is `local`.	(local \| peer \| external)	#IMPLIED	No
%global-atts; (xtrf, xtrc)	A set of related attributes, described at %global-atts;	parameter entity	PE not applicable	Not applicable
class, outputclass	Common attributes described in Other common DITA attributes

Examples

Here's an example of a cross-reference to another topic; that topic's title will be used as the link text.

<p>Background information about DITA is provided in the section titled
<xref href="whatsdita.dita#tmmdita"></xref>.</p>

Here's an example of a cross-reference 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.</p>

If you are linking to anything within a topic, you should use the following format in the href attribute:

filename.xml#topicid/elementid

If you are linking within the same file, you can leave off the "filename.xml" part. So, for a section with the ID "mysection", you should use:

#topicid/mysection

For a list item within that section, assuming the item has an ID of "mylist", use

#topicid/mylist

Regardless of how deeply the target element is nested, the only important pieces are the ID of the containing topic, and the ID of the target element. IDs of topics in DITA must be unique within a file, but IDs of other elements only need to be unique within the topic. You need to be sure that the topic ID is part of your reference.

If your URL has an ampersand in it, you need to code that using a symbol. For example; for this URL:

http://www.ibm.com/docview.wss?rs=757&context=SSVNX5

You need to enter the & in the Href attribute as follows:

<xref href="http://www.ibm.com/docview.wss?rs=757&amp;context=SSVNX5">
Part number SSVNX5</xref>