Merge pull request #938 from robander/conref

Revise conref topics

Author: robander

specification/archSpec/base/conref-attributes-specified-on-elements.dita

@@ -52,7 +52,7 @@
    originating context, even if they are not valid in an intermediate context. </p>
   <p otherprops="examples">For example, if topic A and topic C allow highlighting, and topic B does
       not, then a content reference chain of topic A-to-topic B-to-topic C should preserve any
-      highlighting elements in the referenced content. The result, however it is achieved, must be
+      highlighting elements in the referenced content. The result, however it is achieved, is
       equivalent to the result of resolving the conref pairs recursively starting from the original
       referencing element in topic A.</p>
  </conbody>

specification/archSpec/base/conref-overview.dita

@@ -35,19 +35,18 @@
         <dt>Pushing content from the referencing element</dt>
         <dd>
           <p>The <xmlatt>conaction</xmlatt> attribute reverses the direction of reuse from pull to
-            push. <ph >With a push, the referencing element is rendered before,
-              after, or in place of the referenced element. The location (before, after, or in place
-              of) is determined by the value of the <xmlatt>conaction</xmlatt> attribute.</ph>
-            Because the <xmlatt>conaction</xmlatt> and <xmlatt>conrefend</xmlatt> attributes cannot
-            both be used within the same referencing element, it is not possible to push a range of
-            elements.</p>
+            push. With a push, the referencing element is rendered before, after, or in place of the
+            referenced element. The location (before, after, or in place of) is determined by the
+            value of the <xmlatt>conaction</xmlatt> attribute. The <xmlatt>conaction</xmlatt> and
+              <xmlatt>conrefend</xmlatt> attributes cannot both be used within the same referencing
+            element, so it is not possible to push a range of elements.</p>
         </dd>
       </dlentry>
     </dl>
     <p>A fragment of DITA content, such as an XML document that contains only a single paragraph
-      without a topic ancestor, does not contain enough information for the conref processor to be
-      able to determine the validity of a reference to it. Consequently, the value of a conref must
-      specify one of the following items:</p>
+      without a topic ancestor, does not contain enough information for a conref processor to be
+      able to determine the validity of a reference to it. Consequently, the value of a
+        <xmlatt>conref</xmlatt> attribute must be one of the following items:</p>
     <ul>
       <li>A referenced element within a DITA map</li>
       <li>A referenced element within a DITA topic</li>

specification/archSpec/base/conref-processing.dita

@@ -19,10 +19,10 @@
  </prolog>
  <conbody>
   <note>The DITA <xmlatt>conref</xmlatt> attribute is a transclusion mechanism similar to XInclude
-   and to HyTime value references. DITA differs from these mechanisms, however, in that conref
-   validity does not apply simply to the current content at the time of replacement, but to the
-   possible content given the restrictions of both the referencing document type and the referenced
-   document type.</note>
+      and to HyTime value references. DITA differs from these mechanisms, however, in that conref
+      validity does not apply simply to the current content at the time of replacement, but to the
+      possible resolved content given the restrictions of both the referencing document type and the
+      referenced document type.</note>
    <p>When content is reused between two documents with different domains or constraints, it is
       possible for the reused content to include domain extensions that are not defined for the new
       context, or to include elements that would be constrained out of the new context. When pulling
@@ -33,5 +33,59 @@
   <p>A conref processor <term outputclass="RFC-2119">SHOULD NOT</term> permit resolution of a reuse
       relationship that could be rendered invalid under the rules of either the reused or reusing
       content.</p>
+    <p>When resolving <xmlatt>conkeyref</xmlatt> attributes, processors <term outputclass="RFC-2119"
+        >SHOULD</term> issue a warning when a <xmlatt>conkeyref</xmlatt> reference cannot be
+      resolved and there is no <xmlatt>conref</xmlatt> attribute to use as a fallback. Processors
+        <term outputclass="RFC-2119">MAY</term> issue a warning when a <xmlatt>conkeyref</xmlatt>
+      cannot be resolved to an element and a specified <xmlatt>conref</xmlatt> is used as a
+      fallback.</p>
+    <section id="error-conditions" outputclass="errorcondition">
+      <title>Common error conditions related to conref ranges</title>
+      <p>When encountering the following error conditions, an implementation can optionally issue an
+        error message.</p>
+      <table id="table_pbn_czf_scc">
+        <tgroup cols="2">
+          <colspec colname="col1" colnum="1" colwidth="1*"/>
+          <colspec colname="col2" colnum="2" colwidth="1*"/>
+          <thead>
+            <row>
+              <entry colname="col1">Condition or Issue</entry>
+              <entry colname="col2">Result</entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry colname="col1">The <xmlatt>conref</xmlatt> attribute cannot be resolved in the
+                target document (the target element might have been removed or its id has changed). </entry>
+              <entry colname="col2">The <xmlatt>conref</xmlatt> is ignored.</entry>
+            </row>
+            <row>
+              <entry colname="col1">The <xmlatt>conrefend</xmlatt> attribute cannot be resolved in
+                the target document (the target element might have been removed or its id has
+                changed).</entry>
+              <entry colname="col2">Range cannot be resolved, optional recovery processes the result
+                as a simple conref.</entry>
+            </row>
+            <row>
+              <entry colname="col1">Start and end elements are not siblings in the target
+                document.</entry>
+              <entry colname="col2">If the start element exists, optional recovery processes the
+                result as a simple conref. </entry>
+            </row>
+            <row>
+              <entry colname="col1">End element occurs before the start element in the target
+                document.</entry>
+              <entry colname="col2">If the start element exists, optional recovery processes the
+                result as a simple conref.</entry>
+            </row>
+            <row>
+              <entry colname="col1">An element has a <xmlatt>conrefend</xmlatt> attribute but is
+                missing the <xmlatt>conref</xmlatt> attribute.</entry>
+              <entry colname="col2">No result.</entry>
+            </row>
+          </tbody>
+        </tgroup>
+      </table>
+    </section>
  </conbody>
 </concept>

specification/archSpec/base/conref.dita

@@ -2,10 +2,10 @@
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
 <concept id="conref" xml:lang="en-us">
  <title>Content <ph >reference</ph> (conref)</title>
- <shortdesc >The DITA conref attributes provide mechanisms for reusing content.
-  DITA content references support reuse scenarios that are difficult or impossible to implement
-  using other XML-based inclusion mechanisms like XInclude and entities. Additionally, DITA content
-  references have rules that help ensure that the results of content inclusion remain valid after
+ <shortdesc>The DITA conref attributes provide mechanisms for reusing content. DITA content
+  references support reuse scenarios that are difficult or impossible to implement using many
+  XML-based inclusion mechanisms like XInclude and entities. Additionally, DITA content references
+  have rules that help ensure that the results of content inclusion remain valid after
   resolution</shortdesc>
  <prolog>
   <metadata>

specification/archSpec/base/conref.ditamap

@@ -4,14 +4,26 @@
  <title>Content reference (conref)</title>
  <topicref href="conref.dita" keys="conref">
     <topicref href="conref-overview.dita"/>
+  <topicref keyref="attributes-conref"/>
+  <topicref keyref="attributes-conkeyref"/>
+  <topicref keyref="attributes-conrefend"/>
     <topicref keyref="attributes-conaction"/>
-    <topicref keyref="attributes-conrefend"/>
-    <topicref keyref="attributes-conkeyref"/>
-    <topicref keyref="attributes-conref"/>
     <topicref keyref="attributes-useconreftarget"/>
     <topicref href="conref-processing.dita"/>
     <topicref href="conref-attributes-specified-on-elements.dita"/>
     <topicref href="handling-xref-and-conref-within-topics.dita"/>
+  <topicref href="examples-conref.dita">
+   <topicref href="example-conref-simple.dita"/>
+   <topicref href="example-conref-conkeyref.dita"/>
+   <topicref href="example-conref-range-list.dita"/>
+   <topicref href="example-conref-range-blocks.dita"/>
+   <topicref href="example-conref-range-conkeyref.dita"/>
+   <topicref href="example-conref-conaction-replace.dita"/>
+   <topicref href="example-conref-conaction-pushbefore.dita"/>
+   <topicref href="example-conref-conaction-pushafter.dita"/>
+   <topicref href="example-conref-includes-xref.dita"/>
+   <topicref href="example-conref-includes-xref-and-keyscope.dita"/>
+  </topicref>
   </topicref>
  <reltable title="Source&lt;-->Target">
   <relheader>

specification/archSpec/base/example-conref-conaction-pushafter.dita

@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="example_conaction_pushafter">
+  <title>Example: Using <xmlatt>conaction</xmlatt> to push content after another element</title>
+  <shortdesc>In this scenario, a <xmlatt>conref</xmlatt> and <xmlatt>conaction</xmlatt> are used to
+    push content after an element in another topic.</shortdesc>
+  <conbody>
+    <p>Consider the following topic, which is set up to push a step after a step in another topic.
+      It needs to use two step elements to set up the reuse. The referencing element itself uses
+        <codeph>conaction="mark"</codeph> to mark the referenced element. The element to be pushed
+      immediately follows the marking element and uses <codeph>conaction="pushafter"</codeph>:
+      <codeblock>&lt;steps>
+  &lt;step conaction="mark" conref="example.dita#example/b">
+    &lt;cmd/>
+  &lt;/step>
+  &lt;step conaction="pushafter">
+    &lt;cmd>Do this after B&lt;/cmd>
+  &lt;/step>
+&lt;/steps></codeblock></p>
+    <p>The referenced element is in the file <filepath>example.dita</filepath>, which looks like
+      this before a processor resolves the
+      reference:<codeblock>&lt;task id="example" xml:lang="en">
+  &lt;title>Example topic&lt;/title>
+  &lt;taskbody>
+    &lt;steps>
+      &lt;step id="a">&lt;cmd>A&lt;/cmd>&lt;/step>
+      &lt;step id="b">&lt;cmd>B&lt;/cmd>&lt;/step>
+      &lt;step id="c">&lt;cmd>C&lt;/cmd>&lt;/step>
+    &lt;/steps>
+  &lt;/taskbody>
+&lt;/task></codeblock></p>
+    <p>After the content reference is resolved, the document <filepath>example.dita</filepath>
+      includes the pushed <xmlelement>step</xmlelement> element after the step with
+        <xmlatt>id</xmlatt> set to
+      <keyword>b</keyword>:<codeblock>&lt;task id="example" xml:lang="en">
+  &lt;title>Example topic&lt;/title>
+  &lt;taskbody>
+    &lt;steps>
+      &lt;step id="a">&lt;cmd>A&lt;/cmd>&lt;/step>
+      &lt;step id="b">&lt;cmd>B&lt;/cmd>&lt;/step>
+      &lt;step>&lt;cmd>Do this after B&lt;/cmd>&lt;/step>
+      &lt;step id="c">&lt;cmd>C&lt;/cmd>&lt;/step>
+    &lt;/steps>
+  &lt;/taskbody>
+&lt;/task></codeblock></p>
+  </conbody>
+</concept>

specification/archSpec/base/example-conref-conaction-pushbefore.dita

@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="example_conaction_pushbefore">
+  <title>Example: Using <xmlatt>conaction</xmlatt> to push content before another element</title>
+  <shortdesc>In this scenario, a <xmlatt>conref</xmlatt> and <xmlatt>conaction</xmlatt> are used to
+    push content before an element in another topic.</shortdesc>
+  <conbody>
+    <p>Consider the following topic, which is set up to push a step before a step in another topic.
+      It needs to use two step elements to set up the reuse. The referencing element itself uses
+        <codeph>conaction="mark"</codeph> to mark the referenced element. The element to be pushed
+      immediately preceeds the marking element and uses <codeph>conaction="pushbefore"</codeph>:
+      <codeblock>&lt;steps>
+  &lt;step conaction="pushbefore">
+    &lt;cmd>Do this before B&lt;/cmd>
+  &lt;/step>
+  &lt;step conaction="mark" conref="example.dita#example/b">
+    &lt;cmd/>
+  &lt;/step>
+&lt;/steps></codeblock></p>
+    <p>The referenced element is in the file <filepath>example.dita</filepath>, which looks like
+      this before a processor resolves the
+      reference:<codeblock>&lt;task id="example" xml:lang="en">
+  &lt;title>Example topic&lt;/title>
+  &lt;taskbody>
+    &lt;steps>
+      &lt;step id="a">&lt;cmd>A&lt;/cmd>&lt;/step>
+      &lt;step id="b">&lt;cmd>B&lt;/cmd>&lt;/step>
+      &lt;step id="c">&lt;cmd>C&lt;/cmd>&lt;/step>
+    &lt;/steps>
+  &lt;/taskbody>
+&lt;/task></codeblock></p>
+    <p>After the content reference is resolved, the document <filepath>example.dita</filepath>
+      includes the pushed <xmlelement>step</xmlelement> element before the step with
+        <xmlatt>id</xmlatt> set to
+      <keyword>b</keyword>:<codeblock>&lt;task id="example" xml:lang="en">
+  &lt;title>Example topic&lt;/title>
+  &lt;taskbody>
+    &lt;steps>
+      &lt;step id="a">&lt;cmd>A&lt;/cmd>&lt;/step>
+      &lt;step>&lt;cmd>Do this before B&lt;/cmd>&lt;/step>
+      &lt;step id="b">&lt;cmd>B&lt;/cmd>&lt;/step>
+      &lt;step id="c">&lt;cmd>C&lt;/cmd>&lt;/step>
+    &lt;/steps>
+  &lt;/taskbody>
+&lt;/task></codeblock></p>
+  </conbody>
+</concept>

specification/archSpec/base/example-conref-conaction-replace.dita

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="example_conaction_pushreplace">
+  <title>Example: Using <xmlatt>conaction</xmlatt> to replace content</title>
+  <shortdesc>In this scenario, a <xmlatt>conref</xmlatt> and <xmlatt>conaction</xmlatt> are used to
+    replace content in another topic.</shortdesc>
+  <conbody>
+    <p>Consider the following task in <filepath>example.dita</filepath> that has the
+        <xmlatt>id</xmlatt> attribute set to <keyword>example</keyword>. The task contains a
+        <xmlelement>step</xmlelement> element with the <xmlatt>id</xmlatt> set to
+        <keyword>b</keyword>:</p>
+    <codeblock id="codeblock_scr_wqh_psb">&lt;task id="example" xml:lang="en">
+  &lt;title>Example topic&lt;/title>
+  &lt;taskbody>
+    &lt;steps>
+      &lt;step id="a">&lt;cmd>A&lt;/cmd>&lt;/step>
+      &lt;step id="b">&lt;cmd>B&lt;/cmd>&lt;/step>
+      &lt;step id="c">&lt;cmd>C&lt;/cmd>&lt;/step>
+    &lt;/steps>
+  &lt;/taskbody>
+&lt;/task></codeblock>
+    <p>In order to replace the step with <codeph>id="b"</codeph>, another topic must combine a
+        <xmlatt>conaction</xmlatt> value of <keyword>pushreplace</keyword> with a
+        <xmlatt>conref</xmlatt> attribute that references this
+      <xmlelement>step</xmlelement>:<codeblock>&lt;!-- Steps element within another task -->
+&lt;steps>
+  &lt;step conaction="pushreplace" 
+        conref="example.dita#example/b">
+    &lt;cmd>Updated B&lt;/cmd>
+  &lt;/step>
+&lt;/steps>
+&lt;/task></codeblock></p>
+    <p>The result will be an updated version of <filepath>example.dita</filepath> which contains the
+      pushed <xmlelement>step</xmlelement>:<codeblock>&lt;task id="example" xml:lang="en">
+  &lt;title>Example topic&lt;/title>
+  &lt;taskbody>
+    &lt;steps>
+      &lt;step id="a">&lt;cmd>A&lt;/cmd>&lt;/step>
+      &lt;step id="b">&lt;cmd>Updated B&lt;/cmd>&lt;/step>
+      &lt;step id="c">&lt;cmd>C&lt;/cmd>&lt;/step>
+    &lt;/steps>
+  &lt;/taskbody>
+&lt;/task></codeblock></p>
+  </conbody>
+</concept>

specification/archSpec/base/example-conref-conkeyref.dita

@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="example_simple_conkeyref">
+    <title>Example: Simple <xmlatt>conkeyref</xmlatt> usage</title>
+    <shortdesc>In this scenario, a <xmlatt>conkeyref</xmlatt> attribute is used as an indirect
+    reference to pull content from the referenced element in another topic.</shortdesc>
+    <conbody>
+        <p>Consider the following topic:</p>
+        <codeblock>&lt;task id="setup-widget" xml:lang="en">
+  &lt;title>Setting up the widget&lt;/title>
+  &lt;taskbody>
+    &lt;steps>
+      &lt;step>&lt;cmd>Turn the widget on for the first time.&lt;/cmd>&lt;/step>
+      &lt;step>&lt;cmd>Follow the prompts to select your language and region.&lt;/cmd>&lt;/step>
+      <b>&lt;step conkeyref="reuselibrary/setup-profile">&lt;cmd>&lt;/cmd>&lt;/step></b>
+      &lt;step>&lt;cmd>Step outside and activate the widget.&lt;/cmd>&lt;/step>
+    &lt;/steps>
+  &lt;/taskbody>
+&lt;/task></codeblock>
+    <p>The key is defined as a reference to a resue library:</p>
+    <codeblock>&lt;map>
+  &lt;title>Key definitions&lt;/title>
+  &lt;keydef keys="reuselibrary" href="reuse-library.dita"/>
+  &lt;!-- ... -->
+&lt;/map></codeblock>
+        <p>The library topic <filepath>reuse-library.dita</filepath> is set up as follows:</p>
+        <codeblock>&lt;task id="reuse-library" xml:lang="en">
+  &lt;title>Reuse library topic&lt;/title>
+  &lt;taskbody>
+    &lt;steps>
+      &lt;!-- ... other steps used across tasks ... -->
+      &lt;step id="setup-profile">
+        &lt;cmd>Follow the prompts to set up your name and contact information.&lt;/cmd>
+        &lt;info>Contact information is optional, but recommended.&lt;/info>
+      &lt;/step>
+    &lt;/steps>
+  &lt;/taskbody>
+&lt;/task></codeblock>
+        <p>When the <xmlatt>conkeyref</xmlatt> attribute is resolved, the key resolves to the topic
+      that contains the referenced ID <codeph>setup-profile</codeph>. The result is the same as if
+      the original topic contained
+        <codeph>conref="reuse-library.dita#reuse-library/setup-profile"</codeph> instead of
+        <codeph>conkeyref="reuselibrary/setup-profile"</codeph>. However, the indirection created by
+      using a key allows this reference to resolve differently in other contexts.</p>
+    <p>The processed version of the original topic will include content from the referenced
+      element:</p>
+        <codeblock>&lt;task id="setup-widget" xml:lang="en">
+  &lt;title>Setting up the widget&lt;/title>
+  &lt;taskbody>
+    &lt;steps>
+      &lt;step>&lt;cmd>Turn the widget on for the first time.&lt;/cmd>&lt;/step>
+      &lt;step>&lt;cmd>Follow the prompts to select your language and region.&lt;/cmd>&lt;/step>
+      <b>&lt;step>
+        &lt;cmd>Follow the prompts to set up your name and contact information.&lt;/cmd>
+        &lt;info>Contact information is optional, but recommended.&lt;/info>
+      &lt;/step></b>
+      &lt;step>&lt;cmd>Step outside and activate the widget.&lt;/cmd>&lt;/step>
+    &lt;/steps>
+  &lt;/taskbody>
+&lt;/task></codeblock>
+    </conbody>
+</concept>