Updating conref section per review

Signed-off-by: Robert D Anderson <[email protected]>
robander · Feb 4, 2025 · 8ba00ca · 8ba00ca
1 parent c7adb2d
commit 8ba00ca
Show file tree

Hide file tree

Showing 6 changed files with 104 additions and 87 deletions.
diff --git a/specification/archSpec/base/conref-attributes-specified-on-elements.dita b/specification/archSpec/base/conref-attributes-specified-on-elements.dita
@@ -38,18 +38,16 @@
       attribute with the "-dita-use-conref-target" value, that element <term outputclass="RFC-2119"
         >MUST</term> be treated as equivalent to having that attribute unspecified.</p>
   <p>A given attribute value on the resolved element comes in its entirety from either the
-   referencing element or the referenced element; the attribute values of the referencing and
-   referenced elements for a given attribute are never additive, even if the property (such as
-    <xmlatt>audience</xmlatt>) takes a list of values.</p>
-    <draft-comment author="Kristen J Eberlein" time="04 July 2019" audience="tc-reviewers">
-      <p>Do we want the following paragraph to contain normative RFC-2119 wording?</p>
-    </draft-comment>
+      referencing element or the referenced <ph rev="review-ella">element. The</ph> attribute values
+      of the referencing and referenced elements for a given attribute are never additive, even if
+      the property (such as <xmlatt>audience</xmlatt>) takes a list of values.</p>
     <!--IGNORE may-must-should word-->
-  <p>If the referenced element has a <xmlatt>conref</xmlatt> attribute specified, the above rules
-   should be applied recursively with the resolved element from one referencing/referenced
-   combination becoming one of the two elements participating in the next referencing/referenced
-   combination. The result should preserve without generalization all elements that are valid in the
-   originating context, even if they are not valid in an intermediate context. </p>
+  <p>If the referenced element has a <ph rev="review-ella">content referencing</ph> attribute
+      specified, the above rules <term outputclass="RFC-2119" rev="review-ella">MUST</term> be
+      applied recursively with the resolved element from one referencing/referenced combination
+      becoming one of the two elements participating in the next referencing/referenced combination.
+      The result should preserve without generalization all elements that are valid in the
+      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, is

diff --git a/specification/archSpec/base/conref-processing.dita b/specification/archSpec/base/conref-processing.dita
@@ -18,18 +18,17 @@
   </metadata>
  </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 resolved content given the restrictions of both the referencing document type and the
-      referenced document type.</note>
+  <note>The DITA <xmlatt>conref</xmlatt> attribute is a transclusion mechanism similar to <ph
+        rev="review-ella">XML XInclude</ph> 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
-      or pushing content with the conref mechanism, processors resolving conrefs <term
-        outputclass="RFC-2119">SHOULD</term> tolerate specializations of valid elements. Processors
-        <term outputclass="RFC-2119">MAY</term> generalize elements in the pushed or pulled content
-      fragment as needed for the resolving context.</p>
+      context, or to include elements that would be constrained out of the new context. <ph
+        rev="review-ella">When pulling or pushing content with the conref mechanism, processors
+        resolving conrefs can can optionally generalize specializations as needed for the resolving
+        context.</ph></p>
   <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>
@@ -81,7 +80,8 @@
             <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>
+              <entry colname="col2"><ph rev="review-ella">The <xmlatt>conrefend</xmlatt> attribute
+                  is ignored.</ph></entry>
             </row>
           </tbody>
         </tgroup>

diff --git a/specification/archSpec/base/conref.ditamap b/specification/archSpec/base/conref.ditamap
@@ -8,9 +8,10 @@
   <topicref keyref="attributes-conkeyref"/>
   <topicref keyref="attributes-conrefend"/>
     <topicref keyref="attributes-conaction"/>
-    <topicref keyref="attributes-useconreftarget"/>
     <topicref href="conref-processing.dita"/>
-    <topicref href="conref-attributes-specified-on-elements.dita"/>
+    <topicref href="conref-attributes-specified-on-elements.dita">
+   <topicref keyref="attributes-useconreftarget"/>
+  </topicref>
     <topicref href="handling-xref-and-conref-within-topics.dita"/>
   <topicref href="examples-conref.dita">
    <topicref href="example-conref-simple.dita"/>
@@ -23,6 +24,7 @@
    <topicref href="example-conref-conaction-pushafter.dita"/>
    <topicref href="example-conref-includes-xref.dita"/>
    <topicref href="example-conref-includes-xref-and-keyscope.dita"/>
+   <topicref href="example-conref-ditauseconreftarget.dita"/>
   </topicref>
   </topicref>
  <reltable title="Source&lt;-->Target">
@@ -47,6 +49,7 @@
    </relcell>
    <relcell>
     <topicref keyref="attributes-useconreftarget"/>
+    <topicref href="example-conref-ditauseconreftarget.dita"/>
    </relcell>
   </relrow>
   <relrow>
@@ -57,5 +60,13 @@
     <topicref href="example-keys-conref-redirection.dita"/>
    </relcell>
   </relrow>
+  <relrow>
+   <relcell>
+    <topicref keyref="attributes-useconreftarget"/>
+   </relcell>
+   <relcell>
+    <topicref href="example-conref-ditauseconreftarget.dita"/>
+   </relcell>
+  </relrow>
  </reltable>
 </map>
diff --git a/specification/archSpec/base/ditauseconreftarget.dita b/specification/archSpec/base/ditauseconreftarget.dita
@@ -2,11 +2,9 @@
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
 <concept id="usingthe-dita-use-conref-targetvalue" xml:lang="en-us">
   <title>Using the <keyword>-dita-use-conref-target</keyword> value</title>
-  <shortdesc>The value <keyword>-dita-use-conref-target</keyword> is available on enumerated
-    attributes and can also be specified on other attributes. When an element uses
-      <xmlatt>conref</xmlatt> to pull in content, for any of its attributes assigned a value of
-      <keyword>-dita-use-conref-target</keyword>, the resulting value for those attributes is also
-    pulled in from the referenced element.</shortdesc>
+  <shortdesc>When an element uses <xmlatt>conref</xmlatt> to pull in content, for any of its
+    attributes assigned a value of <keyword>-dita-use-conref-target</keyword>, the resulting value
+    for those attributes is also pulled in from the referenced element.</shortdesc>
   <prolog>
     <metadata>
       <keywords>
@@ -16,10 +14,6 @@
     </metadata>
   </prolog>
   <conbody>
-      <draft-comment author="robander" time="19 May 2021">This topic is moving into the arch spec,
-        but needs further editing to split overview / conceptual info from processing info; this and
-        other conref-attribute topics currently have a bunch of processing info that is missing from
-        the actual "Processing conref" arch spec topics.</draft-comment>
 
       <p>Ordinarily, when an element uses <xmlatt>conref</xmlatt>, any other
         attributes specified locally will be preserved when the reference is resolved. This causes
@@ -37,57 +31,5 @@
           <xmlatt>id</xmlatt> attribute on the <xmlelement>topic</xmlelement> element, because
         "-dita-use-conref-target" does not fit the syntax required by the XML grammar
       files.</p>
-    <example id="example" otherprops="examples">
-      <p>This example shows a DITA map where the <xmlelement>topichead</xmlelement> element uses
-          <xmlatt>conref</xmlatt>. It specifies the <xmlatt>deliveryTarget</xmlatt> attribute as
-        well as the <xmlatt>toc</xmlatt> attribute. In the resolved element,
-          <xmlatt>deliveryTarget</xmlatt> from the referencing element is not preserved because it
-        uses <keyword>-dita-use-conref-target</keyword>. The <xmlatt>toc</xmlatt> attribute from the
-        referencing element overrides the <xmlatt>toc</xmlatt> attribute on the referenced element
-        using normal conref resolution rules.</p>
-      <fig id="example-fig1">
-        <title>Before resolution</title>
-        <codeblock>&lt;map>&lt;title>Conref demonstration&lt;/title>
-  &lt;topichead id="heading"
-             deliveryTarget="pdf"
-             toc="yes"
-             linking="normal">
-    &lt;topicmeta>
-       &lt;navtitle>This is a heading&lt;/navtitle>
-    &lt;/topicmeta>
-    &lt;topicref href="topic.dita"/>
-  &lt;/topichead>
-
-  &lt;topichead conref="#heading"
-             deliveryTarget="-dita-use-conref-target"
-             toc="no">
-  &lt;/topichead>
-&lt;/map></codeblock>
-      </fig>
-      <fig id="example-fig2">
-        <title>Effective result post-resolution</title>
-        <codeblock>&lt;map>&lt;title>Conref demonstration&lt;/title>
-  &lt;topichead id="heading"
-             deliveryTarget="pdf"
-             toc="yes"
-             linking="normal">
-    &lt;topicmeta>
-       &lt;navtitle>This is a heading&lt;/navtitle>
-    &lt;/topicmeta>
-    &lt;topicref href="topic.dita"/>
-  &lt;/topichead>
-
-  &lt;topichead deliveryTarget="pdf"
-             toc="no"
-             linking="normal">
-    &lt;topicmeta>
-       &lt;navtitle>This is a heading&lt;/navtitle>
-    &lt;/topicmeta>
-    &lt;topicref href="topic.dita"/>
-  &lt;/topichead>
-&lt;/map>
-</codeblock>
-      </fig>
-    </example>
   </conbody>
 </concept>
diff --git a/specification/archSpec/base/example-conref-ditauseconreftarget.dita b/specification/archSpec/base/example-conref-ditauseconreftarget.dita
@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="usingthe-dita-use-conref-targetvalue" xml:lang="en-us" rev="review-ella">
+  <title>Example: Using the <keyword>-dita-use-conref-target</keyword> value</title>
+  <shortdesc>In this scenario, an element in a map is reused, with some of the attributes resolved
+    using the <keyword>-dita-use-conref-target</keyword> token.</shortdesc>
+  <prolog>
+    <metadata>
+      <keywords>
+        <indexterm>conref attributes<indexterm>values,
+            <keyword>-dita-use-conref-target</keyword></indexterm></indexterm>
+      </keywords>
+    </metadata>
+  </prolog>
+  <conbody>
+    <p>Consider the following scenario, where a <xmlelement>topichead</xmlelement> element in a DITA
+      map uses <xmlatt>conref</xmlatt>. It specifies the <xmlatt>deliveryTarget</xmlatt> attribute
+      as well as the <xmlatt>toc</xmlatt> attribute.</p>
+    <codeblock id="codeblock_slf_tdn_g2c">&lt;map>&lt;title>Conref demonstration&lt;/title>
+  &lt;topichead id="heading"
+             deliveryTarget="pdf"
+             toc="yes"
+             linking="normal">
+    &lt;topicmeta>
+       &lt;navtitle>This is a heading&lt;/navtitle>
+    &lt;/topicmeta>
+    &lt;topicref href="topic.dita"/>
+  &lt;/topichead>
+
+  &lt;topichead conref="#heading"
+             deliveryTarget="-dita-use-conref-target"
+             toc="no">
+  &lt;/topichead>
+&lt;/map></codeblock>
+    <p>When the content reference is resolved, the <xmlatt>deliveryTarget</xmlatt> attribute from
+      the referencing element is not preserved because it uses
+        <keyword>-dita-use-conref-target</keyword>. Instead, it uses the value
+        <keyword>pdf</keyword> from the referenced element. The <xmlatt>linking</xmlatt> attribute,
+      which is not specified on the referencing element, is also resolved based on the referenced
+      element. The <xmlatt>toc</xmlatt> attribute from the referencing element overrides the
+        <xmlatt>toc</xmlatt> attribute on the referenced element using normal conref resolution
+      rules:</p>
+    <codeblock id="codeblock_zvs_ydn_g2c">&lt;map>&lt;title>Conref demonstration&lt;/title>
+  &lt;topichead id="heading"
+             deliveryTarget="pdf"
+             toc="yes"
+             linking="normal">
+    &lt;topicmeta>
+       &lt;navtitle>This is a heading&lt;/navtitle>
+    &lt;/topicmeta>
+    &lt;topicref href="topic.dita"/>
+  &lt;/topichead>
+
+  &lt;topichead deliveryTarget="pdf"
+             toc="no"
+             linking="normal">
+    &lt;topicmeta>
+       &lt;navtitle>This is a heading&lt;/navtitle>
+    &lt;/topicmeta>
+    &lt;topicref href="topic.dita"/>
+  &lt;/topichead>
+&lt;/map>
+</codeblock>
+  </conbody>
+</concept>
diff --git a/specification/archSpec/base/examples-conref.dita b/specification/archSpec/base/examples-conref.dita
@@ -1,7 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
 <concept id="examples-conref">
-    <title>Examples of conref</title>
+    <title>Examples of content referencing</title>
     <shortdesc>This section contains examples and scenarios that illustrate the use and processing
-        of <xmlatt>conref</xmlatt> and related content-referencing attributes.</shortdesc>
+        of <xmlatt>conref</xmlatt>, <xmlatt>conkeyref</xmlatt>, and related content-referencing
+        attributes.</shortdesc>
 </concept>