<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>
references 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 specifying it in the
<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 are ignored.
This element differs from normal DITA referencing syntax in that it can reference an element within a topic without using the topic's ID. There are two
reasons for this. First, the <anchorid>
element might 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 key values.
It is possible to combine an <anchorid>
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 might
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.
See appendix for information about this element in OASIS document type shells.
+ topic/keyword delay-d/anchorid
@conref
to an id, determined by
original author
<task id="configA">
<title>ABC</title>
<shortdesc>...</shortdesc>
<prolog><metadata>
<exportanchors>
<anchorid id="step1"/>
<anchorid id="step2"/>
<anchorid id="step3"/>
</exportanchors>
</metadata></prolog>
<taskbody>
<steps>
<step id="step1"><cmd>Do this</cmd></step>
<step id="step2"><cmd>Do the other</cmd></step>
<step id="step3"><cmd>And then finish</cmd></step>
</steps>
</taskbody>
</task>
<task id="configB">
<title>..</title>
<shortdesc>..</shortdesc>
<taskbody>
<steps>
<step><cmd>Do the very first thing</cmd></step>
<step conref="componentA/configA.dita#configA/step1"><cmd/></step>
<step><cmd>Do the middle thing</cmd></step>
<step conref="componentA/configA.dita#configA/step2"><cmd/></step>
</steps>
</taskbody>
</task>
@conref
reference 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 might be more up-to-date than the one used by Author 2 when component B was
built.<prolog>
.
<map>
<topicref href="componentA/configA.dita">
<topicmeta>
<exportanchors>
<anchorid id="step1"/>
<anchorid id="step2"/>
<anchorid id="step3"/>
</exportanchors>
</topicmeta>
</topicref>
</map>
@conref
reference is
passed on to the runtime/display format to deal with, rather than being resolved during
native DITA processing.The ID on an <anchorid>
element is first compared with the topic's
id, and then with elements inside that topic. This results in the
following situation.
<map>
<topicref href="componentA/this.dita">
<topicmeta>
<exportanchors>
<anchorid id="this"/>
<anchorid id="that"/>
</exportanchors>
</topicmeta>
</topicref>
</map>
<topic id="this">
<title>This and that</title>
<shortdesc>Oh, you know, this and that.</shortdesc>
<body>
<fig id="that"><p>more of that</p></fig>
</body>
</topic>
@conref
values that target the topic should be delayed.@conref
values that target the figure should be delayed.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 might be exported, in addition to the IDs, so that some
references become bound to the actual component while other references might be redirected.
<map>
<topicref keys="componentAconfig commonconfig"
href="componentA/configA.dita#configA">
<topicmeta>
<exportanchors>
<anchorkey keyref="commonconfig"/>
<anchorid id="step1"/>
<anchorid id="step2"/>
</exportanchors>
</topicmeta>
</topicref>
</map>
The @keys
attributes declares two distinct keys that can be used to refer to this topic (componentAconfig and commonconfig). Only the
second is preserved using <anchorkey>
. A task topic from another
component might reuse steps within this topic in a variety of
ways.
<steps>
<step conkeyref="componentAconfig/step1"><cmd/></step>
<step conkeyref="componentAconfig/step1.5"><cmd/></step>
<step conkeyref="commonconfig/step2"><cmd/></step>
<step conkeyref="commonconfig/step2.5"><cmd/></step>
<step><cmd>And that is the end of that</cmd></step>
</steps>
<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.<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.<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.<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.
<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.@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.The following attributes are available on this element: Universal attribute group (with a narrowed definition of
@id
, given below), @keyref
, and outputclass.
@id
(REQUIRED)@conref
values referencing the indicated ID will not be resolved;
when possible, the original relationship is preserved in
any processed document. Note that this element creates an exception to the general rules
that IDs can 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. This attribute is defined with the XML Data Type
CDATA.