<exportanchors> element is used to delay
@conref resolution within DITA documents. This allows you to process or
display DITA content in a way that will resolve only some of the
values in that content, while remaining values are left for later resolution. The element
contains a list of IDs or keys that are not resolved during the initial preparation
of the content for display; those IDs and keys will be preserved after that preparation, as
will the conref relationship itself.
<exportanchors> element ►can be◄
used within a topic prolog, in which case the defined IDs apply to IDs within that topic
(excluding sub-topics). Alternatively it can be defined in a
<topicmeta> element in a map. In the second case the IDs apply
to the single topic referenced by the current
<topicref> references a file without referencing a
specific topic, it is treated as a reference to the first or root topic. In order to
define anchor ids for a topic that is not the first or root topic, a
<topicref> must directly reference the desired sub-topic.
<anchorid>topic explains the format in detail.
One possible way to use this is with a system that renders DITA dynamically. A user
can process information locally in a way that resolves
@conref for all static information, while delaying resolution for
information that is subject to change. The
element is used to define
@conref values that are delayed.
Another potential use is when DITA is used as the source format for a publishing system
that is able to render information dynamically. In this case some
@conref values might be resolved, while leaving pre-selected
values to be resolved live in that publishing system.
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/keywords delay-d/exportanchors
@conrefto 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>
@conrefreference 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.
<map> <topicref href="componentA/configA.dita"> <topicmeta> <exportanchors> <anchorid id="step1"/> <anchorid id="step2"/> <anchorid id="step3"/> </exportanchors> </topicmeta> </topicref> </map>
@conrefreference 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
<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>
@conrefvalues that target the topic should be delayed.
@conrefvalues 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>
@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>
<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
@conkeyrefvalue 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
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.
The following attributes are available on this element: Universal attribute group.
Return to main page.
Standards Track Work Product
|Copyright © OASIS Open 2016. All Rights Reserved.||25 October 2016|