DITA Proposed Feature # 17d

delayed conref resolution for use of DITA as a delivery format

Longer description

Some runtime engines may be able to handle resolution of conref after the information is built. So the build process will need to distinguish which conrefs to preserve without resolving, and which ids and keys to publish as anchors usable by others in a larger environment.

Scope

Major

Use Case: Runtime resolution of conref to an id, determined by original author

  1. Author 1 creates topics for Eclipse 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:
    <task id="aconfig">
    	<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>
  2. Author 2 is working on Eclipse component B, that prereqs Eclipse component B.
  3. Author 2 creates a configuration task that uses two steps from the configuration task in Eclipse component B:
    <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>
    </task>
  4. Author 2 builds the content for component B into an Eclipse plugin, with the source for component A available during the build 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 Eclipse reuse artifact, so that 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.

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

  1. Author 1 is creating content that will be packaged into multiple Eclipse 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 an Eclipse infocenter, or a helpset that has only one component).
  2. When author 1 builds component A, the author uses a map that exports the ids, rather than exporting the ids from the topic prolog:
    <map>
    <topicref href="componentA/configA.dita">
    	<topicmeta>
    		<exportanchors>
    			<anchorid id="step1"/>
    			<anchorid id="step2"/>
    			<anchorid id="step3"/>
    		</exportanchors>
    	</topicmeta>
    </topicref>
    </map>
  3. The rest of the use case is the same as previous - the conref is passed on to the runtime/display format to deal with, rather than being resolved during native DITA processing.

Use case: Runtime resolution to a key

  1. As in the previous map-based scenario, but the references to componentA uses keys rather than a direct reference, so that the conref can be redirected to a different component when componentA is not installed. The keys may also be exported, in addition to the ids, so that some references become bound to the actual component while other references remain redirectable:
    <map>
    <topicref keys="componentAconfig commonconfig" 
    		href="componentA/configA.dita#configA">
    	<topicmeta>
    		<exportanchors>
    			<anchorkey keyref="commonconfig"/>
    			<anchorid id="step1"/>
    			<anchorid id="step2"/>
    			<anchorid id="step3"/>
    		</exportanchors>
    	</topicmeta>
    </topicref>
    </map>

    <step conref="{componentAconfig}/step1"> would become <step conref="../componentA/configA.dita#configA/step1">

    <step conref="{commonconfig}/step1"> would remain <step conref="{commonconfig}/step1">

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

Rationale for exposing element-level ids in a map

Maps should only reference topics, never elements within a topic, yet this proposal is exposing element-level ids in the map, creating a dependency between the map and the topic's internal structure. This is surely a bad thing.

I'm justifying this to myself by saying that we're not exposing internal topic structure, we're exposing topic metadata - that's where the ids can be exported in the topic prolog, and we do allow prolog metadata for a topic to be stored either in the topic or in the map, so that's consistent.

So I think of it not as internal structure of the topic that's being exposed, but metadata about the topic: "these are the hooks into the topic - in addition to the topic id - that we as providers guarantee have a valid target and will not break randomly next time we publish".

Technical Requirements

  1. Add domain to identify ids within each topic that should be made public to act as anchors for others to contribute content to. For example, an <exportanchors> element within metadata or topicmeta, specialized off <keywords>, with a list of empty <anchorid> and <anchorkey> elements with required id or keyref attributes. Could be done in topic or in map.
  2. Defer resolution of conrefs that target exported ids or keys.
  3. A minimal implementation might limit this to ids exported in maps (not via topic prolog) and to conrefs that use keyref, since that means all necessary information can be found in the map even when the target component source is not available, which is likely a common scenario.

It could be a bonus if we could also generate a map like that in the third scenario during delivery, like a manifest of what's been delivered, to make it easier for others to find the content they can reuse and keep it up to date. This would make sense for teams that are using ids within topics sparingly, and expect them to be controlled and predictable targets. It would not make sense for teams that are adding ids to every topic.

Costs

Some work for toolkit to introduce DITA Eclipse build and DITA runtime build that preserves or strips attributes as shown. More work for any other delivery vehicle that can and wants to make use of this.

Benefits

Content that can be updated incrementally, even by different providers, and even when the content contains dependencies like reuse relationships. For example, a topic in your email software that includes a task on printing emails that shows how to configure your printer, including the latest settings when the printer software is updated.