Chapter 3, Section 1.1.2.39. xref

1.1.2.39. 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 target of the cross-reference is specified using the href or keyref attributes.

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. The DITA map method allows allows topics to be quickly integrated into new contexts without breaking links.

Cross references that link to elements in other topics should use key-based addressing (keyref) in order to make it possible to have the cross-reference point to different topics in the context of different top-level maps. Cross references that use only direct URI-based addressing (href) to point to other topics create dependencies such that if the topic with the cross-reference is included in a given map, the target topic must also be included or the cross-reference will not 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 used in because it is up to each different map to bind the key used by the cross-reference to the appropriate target.

Note

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 <figure> element, not the <title> element within the <figure> element. Output processing should determine whether the text of the object's title element is used when rendering the cross-reference.

Contains

Note

These models represent only the default document types distributed by OASIS. Actual content models will differ with each new document type.

Doctype	Content model
topic (base), map (base), classifyMap, subjectScheme, learningAssessment, learningBookmap, learningContent, learningMap, learningOverview, learningPlan, learningSummary	( text data or boolean or keyword or ph or b or i or sup or sub or tt or u or q or term or tm or state or data or data-about or foreign or unknown or image or desc) (any number)
topic (technical content), map (technical content), concept, ditabase, glossary, glossentry, glossgroup, reference, task, bookmap	( text data or boolean or keyword or apiname or option or parmname or cmdname or msgnum or varname or wintitle or ph or b or i or sup or sub or tt or u or codeph or synph or filepath or msgph or systemoutput or userinput or menucascade or uicontrol or q or term or abbreviated-form or tm or state or data or data-about or foreign or unknown or image or desc) (any number)
machineryTask	( text data or boolean or keyword or wintitle or ph or b or i or sup or sub or tt or u or menucascade or uicontrol or q or term or tm or state or data or data-about or foreign or unknown or image or desc) (any number)

Contained by

Doctype	Content model
topic (base)	desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, bodydiv, section, sectiondiv, example, linkinfo, b, u, i, tt, sup, sub, area, howtoavoid
map (base), classifyMap, subjectScheme, learningMap	desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, b, u, i, tt, sup, sub, area, howtoavoid
topic (technical content), concept	desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, bodydiv, section, sectiondiv, example, linkinfo, b, u, i, tt, sup, sub, area, howtoavoid, screen, codeph, codeblock, pt, pd, synnote
map (technical content)	desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, b, u, i, tt, sup, sub, area, howtoavoid, screen, codeph, codeblock, pt, pd, synnote
ditabase	desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, bodydiv, section, sectiondiv, example, linkinfo, prereq, context, steps-informal, stepsection, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, refsyn, proptypehd, propvaluehd, propdeschd, proptype, propvalue, propdesc, glossdef, glossUsage, glossScopeNote, b, u, i, tt, sup, sub, area, howtoavoid, screen, codeph, codeblock, pt, pd, synnote
glossary, glossentry, glossgroup	desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, bodydiv, section, sectiondiv, example, linkinfo, glossdef, glossUsage, glossScopeNote, b, u, i, tt, sup, sub, area, howtoavoid, screen, codeph, codeblock, pt, pd, synnote
reference	desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, bodydiv, section, sectiondiv, example, linkinfo, refsyn, proptypehd, propvaluehd, propdeschd, proptype, propvalue, propdesc, b, u, i, tt, sup, sub, area, howtoavoid, screen, codeph, codeblock, pt, pd, synnote
task (strict), task (general)	desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, bodydiv, section, sectiondiv, example, linkinfo, prereq, context, steps-informal, stepsection, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, b, u, i, tt, sup, sub, area, howtoavoid, screen, codeph, codeblock, pt, pd, synnote
bookmap	desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, organizationname, b, u, i, tt, sup, sub, area, howtoavoid, screen, codeph, codeblock, pt, pd, synnote
machineryTask	desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, bodydiv, section, sectiondiv, example, linkinfo, prereq, context, steps-informal, stepsection, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, reqcond, reqcontp, personnel, perscat, perskill, esttime, supequi, supply, spare, safecond, howtoavoid, b, u, i, tt, sup, sub, area, screen
learningAssessment, learningOverview, learningSummary	desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, bodydiv, section, sectiondiv, example, linkinfo, lcIntro, lcObjectivesStem, lcObjective, lcAudience, lcTime, lcPrereqs, lcSummary, lcNextSteps, lcReview, lcResources, lcChallenge, lcInstruction, b, u, i, tt, sup, sub, area, lcInteractionBase, lcQuestionBase, lcInstructornote, lcQuestion, lcOpenAnswer, lcFeedback, lcFeedbackCorrect, lcFeedbackIncorrect, lcAnswerContent, lcItem, lcMatchingItem, lcArea
learningBookmap	desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, organizationname, b, u, i, tt, sup, sub, area, howtoavoid
learningContent	desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, bodydiv, section, sectiondiv, example, linkinfo, lcIntro, lcObjectivesStem, lcObjective, lcAudience, lcTime, lcPrereqs, lcSummary, lcNextSteps, lcReview, lcResources, lcChallenge, lcInstruction, prereq, context, steps-informal, stepsection, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, refsyn, proptypehd, propvaluehd, propdeschd, proptype, propvalue, propdesc, b, u, i, tt, sup, sub, area, lcInteractionBase, lcQuestionBase, lcInstructornote, lcQuestion, lcOpenAnswer, lcFeedback, lcFeedbackCorrect, lcFeedbackIncorrect, lcAnswerContent, lcItem, lcMatchingItem, lcArea
learningPlan	desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, bodydiv, section, sectiondiv, example, linkinfo, lcIntro, lcObjectivesStem, lcObjective, lcAudience, lcTime, lcPrereqs, lcSummary, lcNextSteps, lcReview, lcResources, lcChallenge, lcInstruction, lcClient, lcPlanTitle, lcCIN, lcModDate, lcDelivDate, lcPlanSubject, lcPlanDescrip, lcPlanPrereqs, lcGeneralDescription, lcGoals, lcNeeds, lcValues, lcOrgConstraints, lcEdLevel, lcAge, lcBackground, lcSkills, lcKnowledge, lcMotivation, lcSpecChars, lcWorkEnvDescription, lcPlanResources, lcProcesses, lcTaskItem, lcAttitude, lcPlanObjective, lcJtaItem, lcGapItemDelta, lcLearnStrat, lcAssessment, lcDelivery, lcLMS, lcNoLMS, lcHandouts, lcClassroom, lcOJT, lcConstraints, lcW3C, lcPlayers, lcGraphics, lcViewers, lcResolution, lcFileSizeLimitations, lcDownloadTime, lcSecurity, b, u, i, tt, sup, sub, area, lcInteractionBase, lcQuestionBase, lcInstructornote, lcQuestion, lcOpenAnswer, lcFeedback, lcFeedbackCorrect, lcFeedbackIncorrect, lcAnswerContent, lcItem, lcMatchingItem, lcArea

Inheritance

- topic/xref

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 topic entitled
<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 an element inside of a topic, you should use the following format in the href attribute:

filename.dita#topicid/elementid

If you are linking within the same file, you can leave off the "filename.dita" 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

See DITA addressing for details on using URI references and 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&amp;context=SSVNX5"
scope="external">Part number SSVNX5</xref>

Attributes

Name	Description	Data Type	Default Value	Required?
href	Provides a reference to a resource. See The href attribute for detailed information on supported values and processing implications.	CDATA	#IMPLIED	No
type	Describes the target of a reference. See The type attribute for detailed information on supported values and processing implications.	CDATA	#IMPLIED	No
format	The format attribute identifies the format of the resource being referenced. See The format attribute for details on supported values.	CDATA	#IMPLIED	No
scope	The scope attribute identifies the closeness of the relationship between the current document and the target resource. See The scope attribute for more information on values.	(local \| peer \| external \| -dita-use-conref-target)	#IMPLIED	No
univ-atts attribute group (includes select-atts, id-atts, and localization-atts groups)	A set of related attributes, described in univ-atts attribute group
global-atts attribute group (xtrf, xtrc)	A set of related attributes, described in global-atts attribute group
class, outputclass, keyref	Keyref provides a redirectable reference based on a key defined within a map. See The keyref attribute for information on using this attribute. Class and outputclass are described in Other common DITA attributes

‣ Parent topic: Section 1.1.2. Body elements

‣ Previous topic: Section 1.1.2.38. ul