3.1.3.3.2 anchorid

The <anchorid> element allows an
author to define a conref target that will be resolved dynamically
when rendered for an end user of the content. This element is useful
when doing an initial process of the DITA content prior to final rendering
of the content; it causes specified IDs to be preserved after that
process, and conref relationships that reuse the element will not
be resolved during the initial process.

When the anchorid element is defined within a topic prolog,
the specified IDs will be found within that topic. When an anchorid
element is defined within a topicref element, the specified IDs will
be found within the referenced topic (if the topicref points to a
collection of topics, such as a reference that uses only a file name,
the IDs will be found within the first or root topic).

The only
difference between specifying an anchorid in the prolog and in topicmeta
is that from the map it is possible to export the ID of the entire
referenced topic. If <anchorid id="zero"/> is
specified in the topicmeta, and the referenced topic has an id of
"zero", this means that the anchorid is a reference to the entire
topic. If the topic id is not "zero", then the anchorid is a reference
to the element with id="zero" within that topic.

Along with
the preservation of the element's ID, any conref attribute that references
the element's ID will not be resolved during an initial process. In
that case, the conref will be resolved during a later rendering process.

This
description does not imply that IDs are not discarded when anchorid
is not used; though this element requires that IDs be preserved in
some manner, it is also common for IDs to be preserved when anchorid
is not used. Thus the primary impact of the anchorid element is on
conref resolution.

Many publishing systems for which DITA
is used as a source format do not have a way to dynamically resolve
content references; those systems will not see any benefit from this
element. When DITA is used for those systems, behaviors related to
this element should be ignored.

Why not use topicid/elementid?

This element
differs from normal DITA referencing syntax in that it may reference
an element within a topic without using the topic's ID. There are
two reasons for this. First, the anchorid element may only be defined
in a situation that refers unambiguously to a single topic (in the
prolog, or in the topicmeta for a reference to a topic). Second, it
allows the anchorid to be combined with keyref values.

It is
possible to combine an anchor id with a key in order to delay resolution
of conref in the topic represented by that key (see the second set
of examples below). This would not be possible if the anchorid element
required both the topic id and the element id. That is, keyref allows
a modifiable reference to a topic, so a map may instruct processors
to delay conref for item step1 in the topic represented by the key
"commonconfig". If the anchorid element required a topic id, the delayed
conref would always be bound to that specific topic.

Contains

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

Contained by

Inheritance

+
topic/keyword delay-d/anchorid

Example

Figure 1. Use case 1:
Runtime resolution of conref to an id, determined by original author

Author 1 creates topics for information component A, which is
a common component used by many products. The configuration task for
component A is often reused in whole or in part, so the author assigns
ids to each of the steps in the procedure and exports them.

Author 2 builds the content for component B into a deliverable
format that supports dynamic content resolution. As with traditional
conref, the source for component A must be available during this process.
Because the ids in configA are exported, the build process knows to
preserve the reuse relationship rather than resolve it - so the conref
to the steps becomes an equivalent reuse artifact in that deliverable
format. This way the relationship to component A can be resolved at
runtime, and pick up the user's version of component A, which may
be more up-to-date than the one used by Author 2 when component B
was built.

Figure 2. Use case 2: Runtime resolution to an id exported
by the information builder

Author 1 is creating content that will be packaged into multiple
deliverable components. In one of those components, component A, the
ids should be exported for runtime reuse by other components. In other
components, the ids should not be exported because all reuse is local
(for example, the output is a single infocenter, or a helpset that
has only one component).

When author 1 builds component A, the author uses a map that exports
the ids, rather than exporting the ids from the topic prolog.

The first ID to be exported is "this", which matches the topic
id, so resolution of conref values that target the topic should be
delayed.

The second value is "that", which matches a figure within the
topic, so resolution of conref values that target the figure should
be delayed.

Note that if the "this" is also used within the topic (which is
legal from a DITA perspective), it will not be possible to export
that id, because processors will match on the topic's id first.

Example

In this example, a
set of information contains multiple components. Some references to
component A use keys rather than a direct reference, so that conref
can be redirected to a different component when component A is not
installed. The keys may be exported, in addition to the IDs, so that
some references become bound to the actual component while other references
may be redirected.

The keys attributes declares two distinct
keys that may be used to refer to this topic (componentAconfig and
commonconfig). Only the second is preserved using anchorkey. A task
topic from another component may reuse steps within this topic in
a variety of ways.

The componentAconfig key is not preserved, so the first step becomes <step
conref="componentA/configA.dita#configA/step1"><cmd/></step>.
At that point the anchorid element instructs the step1 ID to be preserved;
for runtime applications which support it, this relationship will
be preserved in the processed DITA output.

The second step with the same key becomes <step conref="componentA/configA.dita#configA/step1.5"><cmd/></step>.
However, conref relationships to step1.5 are not preserved, so this
conref should be resolved into static content.

For step three, the map instructs that both the key commonconfig
and the ID step2 should be preserved in any content generated for
this DITA topic. For formats that support runtime resolution through
keys, a process must convert the conkeyref value into an equivalent
value for that format.

Although resolution for the key used in step four is delayed,
the specific element that is referenced should not be delayed. Thus
the fourth step becomes <step conref="componentA/configA.dita#configA/step2.5"><cmd/></step>.
This value is then processed as an ordinary conref value.

This allows the information assembler to resolve references
that must be to componentA while deferring references that can be
fulfilled by alternative component content.

Note: This example
demonstrates why the anchorid element cannot reference an element
with the usual topicid/elementid format. If the two anchorid elements
in the example had been set to config/step1 and config/step2, then
they would only ever apply in a topic with id="config". It would not
be possible to redirect the key to another topic, but still preserve
conref behaviors as desired.

Note: Although it
is not specifically called out in this example, it is possible to
delay conref resolution for an entire topic using the key. If conkeyref
on a task topic element is set to "componentAconfig", which is
not delayed, the conref will be evaluated as usual. However, if
conkeyref on the task is set to "commonconfig", which is delayed,
resolution of conref on that element should be delayed by a processor.

Attributes

Name

Description

Data Type

Default Value

Required?

id

Indicates an ID within the a specific topic that will be
preserved during processing. Any conref values referencing the indicated ID
will not be resolved; when possible, the original relationship should be
preserved in any processed document. Note that this element creates an
exception to the general rules that IDs may only be used once within a single
topic or within a map; this is because the ID is actually a pointer to another
target, rather than being a target itself.

CDATA

#REQUIRED

Yes

keyref

Keyref provides a redirectable
reference based on a key defined within a map. See
The keyref attribute for information on
using this attribute.

CDATA

#IMPLIED

No

conref-atts attribute group (conref, conrefend, conaction,
conkeyref)

A set of related attributes; includes all of the attributes
described in
id-atts attribute groupexcept for the id attribute.