XrefUse 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.
[edit] 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 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'''&'''context=SSVNX5">
Part number SSVNX5</xref>
[edit] Contains
[edit] Contained by
| Doctype
| Parents
|
| bookmap
| desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, organizationname
|
| map
| desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry
|
| ditabase
| desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, section, example, linkinfo, prereq, context, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, refsyn, proptypehd, propvaluehd, propdeschd, proptype, propvalue, propdesc, glossdef, screen, b, u, i, tt, sup, sub, codeph, codeblock, pt, pd, synnote, area
|
| topic
| desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, section, example, linkinfo, screen, b, u, i, tt, sup, sub, codeph, codeblock, pt, pd, synnote, area
|
| task
| desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, section, example, linkinfo, prereq, context, cmd, info, tutorialinfo, stepxmp, choice, choptionhd, chdeschd, choption, chdesc, stepresult, result, postreq, screen, b, u, i, tt, sup, sub, codeph, codeblock, pt, pd, synnote, area
|
| concept
| desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, section, example, linkinfo, screen, b, u, i, tt, sup, sub, codeph, codeblock, pt, pd, synnote, area
|
| reference
| desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, section, example, linkinfo, refsyn, proptypehd, propvaluehd, propdeschd, proptype, propvalue, propdesc, screen, b, u, i, tt, sup, sub, codeph, codeblock, pt, pd, synnote, area
|
| glossary
| desc, p, note, lq, q, sli, li, itemgroup, dt, dd, fig, figgroup, pre, lines, ph, stentry, draft-comment, fn, entry, abstract, section, example, linkinfo, glossdef, screen, b, u, i, tt, sup, sub, codeph, codeblock, pt, pd, synnote, area
|
[edit] Inheritance:
- topic/xref
[edit] 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
|
| type
| Describes the target of a cross-reference. See The type attribute for
detailed information on supported values and processing implications.
| CDATA
| #IMPLIED (Processed as if the target were of type "topic", or inherited from an ancestor)
| No
|
| format
| The format attribute identifies the format of the resource being
cross 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.
- Set scope to local when the resource is part of the current set of content.
- 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.
- See Using the -dita-use-conref-target value for more information on -dita-use-conref-target.
The processing default is local. If no value is
specified, but the attribute is specified on an ancestor within a map or within
the related-links section, the value will inherit from the closest ancestor.
| peer | external | -dita-use-conref-target)
| #IMPLIED
| No
|
| %univ-atts; (%select-atts;, %id-atts;, %localization-atts;)
| A set of related attributes, described at %univ-atts;
| parameter entity
| PE not
applicable
| Not applicable
|
| %global-atts; (xtrf, xtrc)
| A set of related attributes, described at %global-atts;
| parameter entity
| PE not
applicable
| Not applicable
|
| class, outputclass, keyref
| Common attributes described in Other common DITA attributes
|
|
|
|
TOC: Language Specification 1.1
Parent topic: Body elements
Previous topic: keyword
Next topic: ol
|
|
