DITA Proposed Feature # 17b

conref: supporting reuse with delta (applying changes to the reused content).

Longer description

Lets reusers say "that's a lovely task but I need to add a new first step and third step" without refactoring the original task into a bunch of little chunks, or pointing individually at every element in the task. Also allows potential new applications, such as a source topic that provides a template, and reusing topics that pull in the template as a starting point - automatically getting updates to all affected files when the template changes.

Scope

Major

Use Case

Author creates conref to target structure (eg <ol id="x"> element).
Within the conreffing <ol conref="> element, the author wants to add a new item between the second and third items in the target list.
The author of the target has helpfully provided an "id" attribute on each item to allow them to be reused and extended.
The author of the conref adds two child elements: one to identify the place to insert, and one to do the actual insertion. e.g. <li conref="target.dita#target/marker1" conaction="marker""/> <li conaction="addafter">this comes after the marker</li>
When the conref is resolved, the list is pulled in, and the content of "addafter" is inserted after the marked list item "marker1".

Figure 1. Target doc

<ol id="x">
	<li>a</li>
	<li id="marker1">b</li>
	<li>c</li>
</ol>

Figure 2. Referencing doc

<ol conref="target.dita#target/x">
	<li conref="target.dita#target/marker1 conaction="marker"/>
	<li conaction="addafter">b.1</li>
</ol>

Technical Requirements

Several key values to be recognized by processors, and associated with the marker on either the same element or an adjacent element, as follows:

addbefore

<li conaction="addbefore">something</li>
<li conref="target.dita#target/marker1 conaction="marker"/>

addafter

<li conref="target.dita#target/marker1 conaction="marker"/>
<li conaction="addafter">something</li>

replace

	<li conref="target.dita#target/marker1 conaction="replace">something</li>

Note that the reason to have two elements for "addafter" or "addbefore" is so that we can leverage the rules of the local document type to ensure that in fact it is valid to add another element after the target one. Then standard conref processing ensures that the same or equivalent rules are in place in both doctypes, so if it is valid to add an element after the marker in the conreffing context, it must be okay in the conreffed context as well.

Costs

A new attribute, conaction. Plus cost to implementers.

Benefits

Substantial benefits. Reuse becomes much more flexible, and allow much finer granularity of control. Reuse that was too expensive to manage before now becomes manageable. Reuse and change criteria become managed by the reusing document, instead of being managed via conditional processing in a shared document. Because different concerns are now managed in different documents, reuse becomes more scalable and less risky than in the traditional shared document case.

Also opens up potential new applications for reuse, such as updatable templates for authoring.

Time Required

Several meetings to agree on design, plus cost to implement.