`<anchorref>`

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 1. 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 2. 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.