DITA Proposed Feature # 17e

conref by "push"

Longer description

Allow authors to "push" content into a specified anchor place or identified element, or relative to that place (eg immediately after or before the anchor point).

Scope

Major

Use case

  1. Author A contributes a topic to an information set that provides configuration instructions for the product.
  2. Author B contributes content for a particular product component that requires an additional configuration step.
  3. Author A adds ids to each step in the default configuration procedure
  4. Author B creates a topic that pushes a new step into that default procedure, relative to an existing step.
Figure 1. Source topic - default.dita
<task id="x">
	...
	<taskbody>
		<steps>
			<step id="a">A</step>
			<step id="b">B</step>
			<step id="c">C</step>
		</steps>
	</taskbody>
</task>
Figure 2. Referencing topic - push.dita
<task id="z">
	...
	<taskbody>
		<steps>
			<step conref="default.dita#x/b" conaction="mark"><cmd/></step>
			<step conaction="pushafter">B.1</step>
		</steps>
</task>
Figure 3. Resolved default.dita post-conref
<task id="x">
	...
	<taskbody>
		<steps>
			<step id="a">A</step>
			<step id="b">B</step>
	 		<step>B.1</step>
			<step id="c">C</step>
		</steps>
	</taskbody>
</task>

Limitations

As with conref range, there is a danger of pushing content into invalid locations unless we add some restrictions. For example, if we let users push a <cmd> element before a target <stepresult>, the resolved content will have two <cmd> elements (not even necessarily in valid locations).

The restrictions introduced for conref range should also be valid here - although the specialization requirements are reversed (that is, it is valid to push a specialized element into a less specialized target using generalization, which means the referencing element can be a specialization of the target but not vice versa):
  • Both the "mark" and the "push" elements must be of the same type as each other, as well as of the same type (or a specialization of) the target
  • The container elements of the reference and target must be of the same type (or the reference container can be a specialization of the target).

For example, pushing a <step> after a target <li> in <ol> is valid, because <step> is a specialization of <li> and <steps> is a specialization of <ol>; but pushing the same <step> after a target <li> in <ul> would not be valid, because the processor cannot guarantee that <ul> has a compatible content model with <steps> because they are not related through specialization.

Technical Requirements

Add a conaction attribute, with four values:
pushreplace
<li conref="default.dita#x/b" conaction="pushreplace">something</li>
pushbefore, mark
<li conaction="pushbefore">something</li>
<li conref="default.dita#x/b" conaction="mark"/>
pushafter, mark
<li conref="default.dita#x/b" conaction="mark"/>
<li conaction="pushafter">something</li>

Rationale for "mark" action

We need some way of ensuring that multiple elements are allowed in the target. If the reference's container allows multiple elements, and the container is the same as or a specialization of the target's container, then we know the target's container allows multiple elements. So we need to have multiple elements in the referencing context to ensure that multiple elements will be valid in the target context. The separate "mark" and "pushafter/pushbefore" meet this requirement and ensure that the resolved result will be valid.

Costs

New attribute with new values; processing support for this attribute.

Benefits

Lets team members contribute updates to a common topic without creating a new version of the topic, and without requiring changes to the topic itself each time an update is contributed. Control of the change is in the hands of the person requiring the change, so that the owner of the volatile topic does not become a bottleneck for competing change requests.

Combined with "delayed conref resolution", meets the Eclipse requirement for pushing new content into common components (the configuration example above is a real one).