<anchorkey> 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 allows specified keys to be preserved after that process,
and conref relationships which use that key will not be resolved during that initial
@keyref attribute is specified on an
element, it indicates that any conref relationships using that key will not be resolved.
Applications that support run-time resolution of
@conref with keys will then
be able to dynamically resolve this
@conref at display time.
There is no difference between specifying
<anchorkey> within a map (in
<topicmeta>) and specifying
within a topic. In both cases, processors are instructed to delay resolution of that key for
the current set of information. However, the best practice is to only use
<anchorkey> within a map. If it is specified in a topic, that topic
will define a usage for the key for every user of that topic. This makes the topic less
portable, because users that do not want to delay resolution of that specific key will not
be able to include the topic in their information.
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.
See appendix for information about this element in OASIS document type shells.
+ topic/keyword delay-d/anchorkey
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>
@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
<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>
- The componentAconfig key is not preserved, so the first
<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.
<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
@conkeyrefvalue 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
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.
@conrefresolution for an entire topic using the key. If
@conkeyrefon a task topic element is set to "componentAconfig", which is not delayed, the
@conrefwill be evaluated as usual. However, if
@conkeyrefon the task is set to "commonconfig", which is delayed, resolution of
@conrefon that element should be delayed by a processor.
- Defines a key that, when possible, is preserved in
content generated from the DITA source material. Conref relationships that use this key
are not resolved when generating that material, so that
@conrefmight be resolved at run-time when an end user is reading the content.