DITA Proposed Feature #12013 Referencing a range of elements

Longer description

This feature would allow a user to conref more than one element at a time. For example, this feature would allow a user to conref steps 2 to 5 in a task. Currently, a user wishing to reuse a series of adjacent elements must create a conref to each referenced node. This feature would enable a short-hand allowing a user to denote a range of content references by marking the start and end elements. This proposal has a minor design changes from the original IssueNumber17c.html proposal http://www.oasis-open.org/committees/download.php/15118/IssueNumber17c.html (simplified attribute name and value names ).

Statement of Requirement

• Make it easier for a user to pull in a range of adjacent elements using content references.
• Provide a shorthand so that the user do not need to provide id values for each element, but only the start and end elements.

Use Cases

Reusing a series of elements

An user needs to reuse a series of adjacent elements such as list items.

The reusable content exists in a target DITA topic or map. The elements which will be conref'd to as the start and end of the ranges must have id attributes.

The user will create a range by adding a pair of elements in the source topic. The first element in the source must be the same type as the start element of the target range. The user will add a conref attribute that points to the start target and set the value of the conreftype attribute to "start." The second element in the pair must be the same as the end target element with a conref pointing to the end of the targeted range and should have conref attribute value of "end." The user should only create ranges on target elements that share the same parent element.

Processors will resolve the range by pulling in the start target and following sibling elements across to and including the end target.

Assumptions, Error Conditions and Error Handling

Assumptions for the target instance are:

• Target elements have an id attribute.
• The start and end targets must share the same parent. In other words, the start and end targets must be siblings in the DOM tree. There may be zero or more sibling between the start and end target that will be assumed to be part of the range.
• Element order is significant. In the target document, the start element must precede the end element.
• The contiguous target range of elements do not have to be the same type of element. For instance, a target range could be comprised of a paragraph, followed by an image, followed by a menucascade.

Assumptions for the source instance are:

• When creating a new conref range, authors should create a pair of elements. The first element must have a conref attribute that points to the start of the intended range and must have the conref attribute set to "start". The next element must have conref attribute that points to the end of the intended range and have a conreftype attribute set to "end". The conref range is thus represented by this pair of adjacent elements.
• Order is significant with the pair of conreffing elements as the element with the conref start must be immediately followed by the element with the conref end. In other words, the start and end elements should be adjacent siblings in the DOM tree. If there are elements between the start and end source markers, processing will remove these intermediate elements as part of resolving the conref range.
• Reusers should be careful to ensure to keep the start/end of each start/end conref range paired together in the correct order.
• In the source document, the pair of conref start and end elements must be immediate siblings.
• A range whose start and end conref points are the same is called a "collapsed range" and will act as a single pointer to the DOM element.

Error conditions may occur if

• Either the start or end target elements cannot be resolved (the target elements may have been removed or their ids have been changed).
• The start or end element is removed from target instance.
• The start or end elements in the target instance are moved such that they no longer share a common parent or such that the end element occurs before the start.
• If the start/end source elements in the source instance have been moved (or removed) so that they are no longer siblings.
• if the start/end elements' positions are changed such that the end element occurs before the start element.

These types of error conditions may occur when the author and reuser are different actors. If the author has created a topic which is being reused through the conref range feature, and the author goes and reorders the elements in the target instance, an error condition can be created.

Processors should fail on first error. It is not expected that processors will be able to pull in the referenced range if any of these error conditions are met. Standard XML validation will not be able to catch these error conditions. Tools will need to add additional business rules checking if they need to enforce valid conref ranges. These error conditions will most likely be caught when a processor attempts to resolving a conref range.

Scope

This proposal introduces a new universal attribute that acts as a type modifier on the existing "conref" attribute. The attribute is called "conreftype" and would modify the default action for processing content references.

Technical Requirements

Add a new attribute in the DTD and XML Schema.

The change in DTD syntax in the id-atts entity within commonElements.mod

<!ENTITY % id-atts  
            'id         NMTOKEN                            #IMPLIED
             conref     CDATA                              #IMPLIED
             conreftype    (start | end )           #IMPLIED'>

The change in XML Schema syntax:

<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="conreftype" type="conreftype-atts.class"/>
    </xs:attributeGroup>
    
    <xs:simpleType name="conreftype-att.class">
            <xs:restriction base="xs:string">
                <xs:enumeration value="start"/>
                <xs:enumeration value="end"/>
                
             </xs:restriction>
    </xs:simpleType>

Base processing would change to pull in the start and end content references as well as all intermediate contiguous nodes. Base processing should operate on the assumption that the reuser will place the start and end pointers adjacent to each other. In the sourced document, the start and end elements must appear in the correct order (start before end), must have ids set and should share the same parent element. Although ids are not necessary on the intermediate ids for processing purposes, authors should be encouraged to set ids on all items intended for reuse to make the system more flexible.

<topic id="x">
 	...
 	<body>
 		<of>
 			<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>
 		</of>
 	</body>
 </topic>
 

 <topic id="y">
 	...
 	<body>
 		<of>
 			<li>My own first step</li>
 			<li conref="target.dita#x/bear" conreftype="start"/>
 			<li conref="target.dita#x/dog" conreftype="end"/>
 			<li>And a different final step</li>
 		</of>
 	</body>
 </topic>
 

 <topic id="y">
 	...
 	<body>
 		<of>
 			<li>My own first step</li>
 			<li>B</li>
 			<li>C</li>
 			<li>D</li>
 			<li>And a different final step</li>
 		</ol>
 	</body>
</topic>

New or Changed Specification Language

• The Language Reference topic for id-atts would change.
• The Architectural topic for content inclusion (conref) would have some additions.

Costs

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

Benefits

If a reuser wants to grab a range, then marking the range by start and end values is much easier and much less risky than grabbing the range by pointing to each element individually. When a new element is added within the scope of the range, it is automatically picked up by default.