Content references to a range of elements
Enables users to conref to a range of adjacent elements. Currently, a user wishing to reuse a series of adjacent elements must create a conref to each referenced node. Proposed feature allows a user to denote a range of content references by creating a content reference to the start and end elements.
Ancillary benefits including the ability to conref in intermediary nodes within the conref range including elements with no ids and text nodes.
An user wants to reuse a series of adjacent elements such as list items.
The reusable content exists in a target DITA topic or map.
The user creates a new <li> element with a conref to the start element of the intended range. The user set the conrefend attribute to the end of the intended range. Both the start and end target elements must have their ids set, share same parent element and must be the same element type (or can be generalized down to the same element type). Element order is significant as the start target element must precede the end target element.
With this proposal, the conref range is represented by a single element with restrictions on the start and end types as well as the parent container. The start and end element types must match to minimize the potential for invalid content on the referencing side or an invalid result after resolution.
The intermediary, contiguous nodes in the middle of the range do not have to be heterogenous. For instance, a target range can be comprised of <p>, followed by <image> followed by <menucascade>, followed by <p>. The intermediary nodes in the range should be valid types but there are no equivalent elements that they can be compared to in the referencing document.
The parent container of the target start and end elements must be the same element type (or generalizable down to the same element type) as the parent of the conref'ing element. Restricting the parent element container limits reuse to cases known to be valid in the general case.
But it does limit reuse to cases we know are valid in the general case (barring contextual rules that would eliminate the repeatability of element-level reuse).
Processors will resolve the range by pulling in the start target and following sibling DOM nodes across to and including the end target.
<topic id="x"> ... <body> <ol> <li id="apple">A</li> <li id="bear">B</li> <li id="cat">C</li> <li id="dog">D</li> <li id="eel">E</li> </ol> </body> </topic>
<topic id="y"> ... <body> <ol> <li>My own first step</li> <li conref="topic.xml#x/bear" conrefend="topic.xml#x/dog"/> <li>And a different final step</li> </ol> </body> </topic>
<topic id="y"> ... <body> <ol> <li>My own first step</li> <li id="bear">B</li> <li id="cat">C</li> <li id="dog">D</li> <li>And a different final step</li> </ol> </body> </topic>
<topic id="x">
...
<body>
<p id="p1">First para</p>
<ol id="mylist">
<li id="apple">A</li>
<li id="bear">B</li>
<li id="cat">C</li>
<li id="dog">D</li>
<li id="eel">E</li>
</ol>
<p id="p2">Second para</p>
</body>
</topic>
When encountering an error condition, an implementation may but need not issue an error message.
| Condition or Issue | Result |
|---|---|
| The conref attribute cannot be resolved in the target document (the target element may have been removed or its ids has changed). | The conref is ignored. |
| The conrefend attribute cannot be resolved in the target document (the target element may have been removed or its ids has changed). | Range cannot be resolved, optional recovery processes the result as a simple conref. |
| Start and end elements are not siblings in the target document. | If the start element exists, optional recovery processes the result as a simple conref. |
| End element occurs before the start element in the target document. | If the start element exists, optional recovery processes the result as a simple conref. |
| An element has a conrefend attribute but is missing the conref | No result. |
Conref processing behaviours need to be addressed in a separate document. Two major implementations are currently using a different order of operations. One filters first and then resolves the conrefs, the other resolves the content and then filters. Missing content due to filtering order of operations is an error condition.
Generalization of content references should follow the default behaviour defined in the specification.
Introduce a universal attribute "conrefend" that modifies the default action for processing content references. The "conrefend" attribute uses the same addressing rules as standard "conref".
It uses the same addressing as regular "conref".
Add a new attribute in the DTD and XML Schema.
The singleton design would require an additional "conrefend" attribute used to address the end of the conref's range.
DTD syntax change in the id-atts entity within commonElements.mod:
<!ENTITY % id-atts
'id NMTOKEN #IMPLIED
conref CDATA #IMPLIED
conrefend CDATA #IMPLIED'>
<xs:attributeGroup name="id-atts">
<xs:annotation>
<xs:documentation>ID attributes (%id-atts;) is a parameter entity declaration in the
topic DTD that includes attributes that enable the naming and referencing
of elements in a DITA topic: <keyword>id</keyword> and <keyword>conref</keyword>.
</xs:documentation>
</xs:annotation>
<xs:attribute name="id" type="xs:NMTOKEN"/>
<xs:attribute name="conref" type="xs:string"/>
<xs:attribute name="conrefend" type="conrefend-atts.class"/>
</xs:attributeGroup>
<xs:simpleType name="conrefend-att.class">
<xs:restriction base="xs:string">
<xs:enumeration value="start"/>
<xs:enumeration value="end"/>
</xs:restriction>
</xs:simpleType>