DITA Proposed Feature #12013 Referencing a range of elements

Content references to a range of elements

Longer description

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.

Statement of Requirement


Ancillary benefits including the ability to conref in intermediary nodes within the conref range including elements with no ids and text nodes.

Use Cases

Conref a range of elements

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.

Figure 1. List example: Source topic.xml with ids
<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>
 
Figure 2. List example: Reusing topic with conrefs

 <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>
 
Figure 3. List example: Processed result of reusing 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>
Figure 4. Block level example: Source topic.xml with ids
<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>
 
Figure 5. Block level example: Reusing topic with conrefs

 <topic id="y">
 	...
 	<body>
 		<li conref="topic.xml#x/p1" conrefend="topic.xml#x/p2"/>
 	</body>
 </topic>
 
Figure 6. Block level example: Processed result of reusing topic
 <topic id="y">
 	...
 	<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>

Error Conditions

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.

Processing behaviours

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.

Scope

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".

Technical Requirements

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>


New or Changed Specification Language


Costs

Time to design 2 meetings; cost to implement is higher.