anchorref

Darwin Information Typing Architecture (DITA) Version 1.3 Part 2: Technical Content Edition

version
1.3
author
OASIS DITA Technical Committee

The anchorref element is used to reference an anchor element in a map. The contents of an anchorref element are rendered both in the original authored location and at the location of the referenced anchor element. The referenced anchor element might be defined in the current map or another map. When possible, this integration is done when displaying the map with anchor to an end user.

This function of the anchorref element is similar to that provided by the anchorref attribute of the map element. However, instead of attaching an entire map to an anchor point, this element allows the author to attach only the contents of a single map branch. This enables architects to reuse a branch of content without reusing the entire map.

If the rendering platform does not support runtime integration of navigation based on the anchor point, a build system should treat the anchorref element similar to a "conref push" instruction by pushing the content to the spot that contains the anchor. Note that many anchorref elements might push content to the same point; the order in which items are pushed is left undefined, although the order within a single anchorref is preserved.

Metadata cascading takes place in the original authored context, because the branch of content defined with the anchorref remains independent from the referenced map. The anchorref content does not take on the cascading metadata at the anchor location. For example, if the map containing the anchorref element sets a local copyright, that copyright cascades to the anchorref element and its children; it is retained after the content is rendered at the target anchor element.

By default, the content of the anchorref element is rendered at both the anchor target and the original location. To prevent the content from being rendered at the location of the anchorref element, set toc="no" on the anchorref element, and then set toc="yes" on each of its children so that they will not inherit the toc="no" setting.

Content models

See appendix for information about this element in OASIS document type shells.

Inheritance

+ map/topicref mapgroup-d/anchorref

Example

Figure. Initial map contents
<topicref href="carPrep.dita">
    <topicref href="beforePrep.dita"/>
    <anchor id="prepDetail"/>
    <topicref href="afterPrep.dita"/>
</topicref>
<!-- ... -->
<topicref href="astroTasks.dita">
    <topicref href="astroOverview.dita"/>
    <anchorref href="#prepDetail">
        <topicref href="astroChecklist.dita"/>
        <topicref href="otherPreparation.dita"/>
    </anchorref>
    <topicref href="astroConclusion.dita"/>
</topicref>
Figure. Effective result of evaluating the anchorref element
<topicref href="carPrep.dita">
    <topicref href="beforePrep.dita"/>
    <anchor id="prepDetail"/>
    <topicref href="astroChecklist.dita"/>
    <topicref href="otherPreparation.dita"/>
    <topicref href="afterPrep.dita"/>
</topicref>
<!-- ... -->
<topicref href="astroTasks.dita">
    <topicref href="astroOverview.dita"/>
    <topicref href="astroChecklist.dita"/>
    <topicref href="otherPreparation.dita"/>
    <topicref href="astroConclusion.dita"/>
</topicref>

Attributes

The following attributes are available on this element: Universal attribute group, Link relationship attribute group (with narrowed definitions of href, type, and format, all given below), Attributes common to many map elements, Topicref element attributes group, outputclass, keys, and keyref.

href
A pointer to an anchor element in this or another DITA map. When rendered, the contents of the current element will be copied to the location of the anchor. See The href attribute for supported syntax when referencing a map element.
type
Describes the target of a reference. For the anchorref element, this value defaults to "anchor", because the element is expected to point to an anchor element in this or another map.
format
The format attribute identifies the format of the resource being referenced. For the anchorref element, this value defaults to "ditamap", because the element references a point in a map.