Date and version information
|• ||The latest revision date for this proposed feature document is 2012 January 5.
|• ||This feature was originally proposed in email on 2008 September 9
|• ||Though originally proposed by Jeff Ogden, Paul Grosso is now the champion of the proposal.
As explained in Jeff’s email
, we need a syntax that “allows sections of DITA markup that include URI references to be written in a self-contained location independent fashion.” For example, currently, if you want to have a link from explanatory text to a figure within a section of a topic, that link’s href needs to include the topic id of the surrounding topic. If you then want to reuse that section in another topic, you cannot use the section as authored; instead, you have to make a copy of it and change the topic id in the link’s href.
Currently, the syntax for same document references is #topicid/elementid. The suggested alternate syntax (the current syntax would continue to be allowed) for same document/same topic references is #./elementid where the dot represents the id of the closest ancestral topic after conref processing. (In the case of #. within a @conref attribute, the dot would be expanded to be what would be the closest ancestral topic to this element after all ancestral conrefs are processed.)
This syntax is only used for same document topic references (that is, relative URI references that start with #). It is an error to use this syntax when a path or filename is given.
The uses for a same document/same topic reference syntax are similar to the uses for the existing same document reference syntax. The syntax allows sections of DITA markup that include URI references to be written in a self-contained location independent fashion. The markup could be moved from or included from one topic document to another using copy and paste, content references, xincludes, entities, or other means without the need to adjust the URI reference to include the id of the topic at the target location.
|• ||In a topic about checking tire air pressure, there is a fairly generic section with a figure of the tire and a reference (xref) to that picture in an accompanying paragraph of text. If the topic’s id is “tire-pressure” and the figure’s id is “tire”, currently the xref’s href would have to be #tire-pressure/tire. One cannot now reuse (e.g., via copy and paste) that section into a topic about changing a flat, because the reference would not be valid. With the new syntax, the xref’s href can be #./tire, and the section can be copied into another topic without change because the href will resolve as a same-topic reference in any topic.
|• ||In a topic, there is a numbered list (or set of steps) where item 2 has a cross reference to item 4. If that is written as follows in a topic whose id="xyz":
<li>Step 2 with <xref href="#xyz/step4"></xref></li>
<li id="step4">Step 4.</li>
</ol>and it is then copied into a topic whose id="abc", the reference may not be as expected. Using the new syntax:
<li>Step 2 with <xref href="#./step4"></xref></li>
<li id="step4">Step 4.</li>
</ol>the reference from item 2 will be to item 4 within the same list (in the same topic) regardless of the ancestral topic id.
|• ||Authors will find it easier to make intra-topic references in that they don’t have to remember or use the topic id.
|• ||Because the new syntax allows intra-topic references that do not have the topic id hardwired into the address, reuse of sub-topic content by multiple topics will be made much simpler.
|• ||A fair number of people are expected to use this feature.
|• ||This will be a benefit to users who want to be able to copy existing content in multiple topics without having to edit intra-topic links for each topic into which they insert the content.
|• ||No impact on the DTDs and XSDs.
|• ||Minor impact to the DITA specification:
|– ||18.104.22.168.2 URI-based (direct) addressing, URIs and DITA fragment identifiers, 4th para says “When addressing a non-topic element within a DITA topic, a URI reference must use a fragment identifier that contains the ID of the ancestor topic element of the non-topic element being referenced....” This needs to be modified to allow for the new syntax. In the same topic, under URI reference syntax examples, we should add a sample syntax example of the new syntax.
|– ||22.214.171.124 The href attribute, 4th para says “An href value consisting of a URI with a fragment identifier must have a valid DITA local identifier as the portion after the hash. A DITA local identifier consists of topicID/elementID for a subelement of a topic and of elementID for topics, maps, and map subelements.” This needs to be modified to allow for the new syntax. In the same topic, we should add an example of the new syntax.
|– ||We will need to add this change under Changes from previous versions appendix.
|• ||Relatively minor impact to DITA tools to recognize and handle the new syntax:
|– ||Publishing and transformation engines will need to recognize and resolve references that use the new syntax.
|– ||Authoring tools may need to be updated to support inserting, modifying, validating, and/or resolving references in the new syntax.
|• ||DITA community-at-large: should be an obvious and useful extension to our current addressing capabilities. Its use is optional and upward compatible—no existing documents or processes would be affected.
While discussing initial versions of this proposal with several other TC members, it was realized that the DITA 1.2 specification is not clear about what happens with addresses within conref-ed content. In the case below under “Examples”, if Reference #1 in topicA.dita read <xref href="#topicA/pid1"/>, it is not clear if the resulting Reference #1 in Topic B should refer to the paragraph within Section A2 in Topic A whose contents is “paraA” or to the paragraph within Section B2 in Topic B whose contents is “paraB”. We will probably want to address this ambiguity in DITA 1.3. However, this ambiguity is independent of this current proposal and is neither a result of the current proposal nor further complicated by this current proposal.
Authors will be able to use the new syntax to reference elements within the same topic.
Tools would need to expand handling of URI reference values to understand and properly process the new syntax.
Suppose we have topicA.dita that consists of:
<p>Reference #1: <xref href="#./pid1"/></p>
<p>Reference #2: <xref href="#./pid2"/></p>
and topicB.dita that consists of:
and then suppose both topics were referenced by the same map. In the resulting output, there would be two xrefs in Topic A and two in Topic B. They would refer to elements as follows:
|1.||Reference #1 in Topic A would reference the paragraph within Section A2 in Topic A whose contents is “paraA”
|2.||Reference #2 in Topic A would reference the paragraph within Section A1 in Topic A whose contents is “paraC”
|3.||Reference #1 in Topic B would reference the paragraph within Section B2 in Topic B whose contents is “paraB”
|4.||Reference #2 in Topic B would reference the paragraph within the section (pulled in by the conref) in Topic B whose contents is “paraC”