3.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.

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

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  

Add key-based addressing examples

See 2.1.3.4 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 &amp; 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 3.4.2.1 The href attribute for detailed information on supported values and processing implications.

CDATA

#IMPLIED

No

type

Describes the target of a reference. See 3.4.2.8 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 3.4.2.9 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 3.4.2.10 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 3.4.1.3 univ-atts attribute group

     

global-atts attribute group (xtrf, xtrc)

A set of related attributes, described in 3.4.1.2 global-atts attribute group

     

class, outputclass, keyref

Class and outputclass are described in 3.4.1.9 Other common DITA attributes

     

Previous Topic:  3.1.1.2.38 ul

Next Topic:  3.1.1.3 Table elements

Parent Topic:  3.1.1.2 Body elements

Sibling Topics:

3.1.1.2.1 alt

3.1.1.2.2 cite

3.1.1.2.3 dd

3.1.1.2.4 desc

3.1.1.2.5 ddhd

3.1.1.2.6 dl

3.1.1.2.7 dlentry

3.1.1.2.8 dlhead

3.1.1.2.9 dt

3.1.1.2.10 draft-comment

3.1.1.2.11 dthd

3.1.1.2.12 example

3.1.1.2.13 fig

3.1.1.2.14 figgroup

3.1.1.2.15 fn

3.1.1.2.16 image

3.1.1.2.17 keyword

3.1.1.2.18 li

3.1.1.2.19 lines

3.1.1.2.20 longdescref

3.1.1.2.21 longquoteref

3.1.1.2.22 lq

3.1.1.2.23 object

3.1.1.2.24 note

3.1.1.2.25 ol

3.1.1.2.26 p

3.1.1.2.27 param

3.1.1.2.28 ph

3.1.1.2.29 pre

3.1.1.2.30 q

3.1.1.2.31 section

3.1.1.2.32 sectiondiv

3.1.1.2.33 sl

3.1.1.2.34 sli

3.1.1.2.35 term

3.1.1.2.36 text

3.1.1.2.37 tm

3.1.1.2.38 ul