Merge pull request #942 from robander/conref

Review comments from conref arch spec review
oasis-tcs · Oct 8, 2024 · 74eaa1b · 74eaa1b
2 parents c6bd8db + 352e185
commit 74eaa1b
Show file tree

Hide file tree

Showing 8 changed files with 54 additions and 54 deletions.
diff --git a/specification/archSpec/base/conref-overview.dita b/specification/archSpec/base/conref-overview.dita
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
 <concept id="conref" xml:lang="en-us">
- <title><ph >Conref overview</ph></title>
+ <title><ph rev="review-ella">Content referencing</ph> overview</title>
  <shortdesc><ph conkeyref="reuse-general/conref-shortdesc"/></shortdesc>
   <prolog>
     <metadata>
@@ -18,17 +18,18 @@
       as defined in <xref href="linking-and-addressing-terms.dita"/>.</p>
     <dl>
       <dlentry>
-        <dt>Pulling content to the referencing element</dt>
+        <dt>Pulling content <ph rev="review-ella">into</ph> the referencing element</dt>
         <dd>
           <p>When the <xmlatt>conref</xmlatt> or <xmlatt>conkeyref</xmlatt> attribute is used alone,
-            the referencing element acts as a placeholder for the referenced element, and the
-            content of the referenced element is rendered in place of the referencing element.</p>
+            the referencing element acts as a placeholder for the referenced <ph rev="review-ella"
+              >element. The</ph> content of the referenced element is rendered in place of the
+            referencing element.</p>
           <p>The combination of the <xmlatt>conrefend</xmlatt> attribute with either
               <xmlatt>conref</xmlatt> or <xmlatt>conkeyref</xmlatt> specifies a range of elements
-            that is rendered in place of the referencing element. <ph >Although
-              the start and end elements must be of the same type as the referencing element (or
-              specialized from that element type), the elements inside the range can be any
-              type.</ph></p>
+            that is rendered in place of the referencing element. <ph rev="review-ella">The start
+              and end elements in a range must be siblings.</ph> Although the start and end elements
+            must be of the same type as the referencing element (or specialized from that element
+            type), the elements inside the range can be any type.</p>
         </dd>
       </dlentry>
       <dlentry>

diff --git a/specification/archSpec/base/conref.dita b/specification/archSpec/base/conref.dita
@@ -2,11 +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 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>
+ <shortdesc rev="review-ella">The DITA conref attributes are mechanisms that enable effective
+  content reuse. DITA content references support complex reuse scenarios that are otherwise
+  challenging or impossible to achieve. In addition, DITA content references have rules to ensure
+  that the content is valid DITA after the content reference has been resolved.</shortdesc>
  <prolog>
   <metadata>
    <keywords>
@@ -16,4 +15,5 @@
    </keywords>
   </metadata>
  </prolog>
+ <conbody/>
 </concept>
diff --git a/specification/archSpec/base/ditauseconreftarget.dita b/specification/archSpec/base/ditauseconreftarget.dita
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
-<reference id="usingthe-dita-use-conref-targetvalue" xml:lang="en-us">
+<!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
@@ -15,14 +15,13 @@
       </keywords>
     </metadata>
   </prolog>
-  <refbody>
-    <section id="section_nwl_xxy_qpb">
+  <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>
-    </section>
-    <section id="section-1"><p>Ordinarily, when an element uses <xmlatt>conref</xmlatt>, any other
+
+      <p>Ordinarily, when an element uses <xmlatt>conref</xmlatt>, any other
         attributes specified locally will be preserved when the reference is resolved. This causes
         problems when attributes are required, because required attributes must be specified
         regardless of whether the <xmlatt>conref</xmlatt> attribute is present. The purpose of the
@@ -37,7 +36,7 @@
         <xmlelement>tgroup</xmlelement>. However, the token is not allowed for the
           <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></section>
+      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
@@ -90,5 +89,5 @@
 </codeblock>
       </fig>
     </example>
-  </refbody>
-</reference>
+  </conbody>
+</concept>
diff --git a/specification/archSpec/base/theconactionattribute.dita b/specification/archSpec/base/theconactionattribute.dita
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
- "reference.dtd">
-<reference id="theconactionattribute" xml:lang="en-us">
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "concept.dtd">
+<concept id="theconactionattribute" xml:lang="en-us">
 <title>The <xmlatt>conaction</xmlatt> attribute</title>
 <shortdesc>The <xmlatt>conaction</xmlatt> attribute allows users to push content from one location
     into another. It causes the <xmlatt>conref</xmlatt> attribute to work in reverse, so that
@@ -14,8 +14,8 @@
       </keywords>
     </metadata>
   </prolog>
-<refbody>
-<section id="section-1"><note>In the descriptions below, the word <i>target</i> always refers to the element referenced by a
+<conbody>
+<note>In the descriptions below, the word <i>target</i> always refers to the element referenced by a
           <xmlatt>conref</xmlatt> attribute.</note><p>There are three possible functions using the <xmlatt>conaction</xmlatt> attribute: replacing an
         element, pushing content before an element, and pushing content after an element. The
           <xmlatt>conaction</xmlatt> attribute always declares the desired function while the
@@ -36,7 +36,7 @@
           not legal to push a list item (<xmlelement>li</xmlelement>) in order to replace a
             <xmlelement>step</xmlelement>, because the list item allows many items that are not
           valid in the specialized context.</li>
-</ul></section>
+</ul>
 <section id="replacing-content">
       <title>Replacing content in another topic</title>
       <p>When the <xmlatt>conaction</xmlatt> attribute is set to <keyword>pushreplace</keyword>, the
@@ -120,6 +120,6 @@ was not addressed in the original proposal.-->
         application can recover by warning the user, ignoring the <xmlatt>conrefend</xmlatt>
         attribute, or with some other implementation strategy.</p>
     </section>
-</refbody>
-</reference>
+</conbody>
+</concept>
 
diff --git a/specification/archSpec/base/theconkeyrefattribute.dita b/specification/archSpec/base/theconkeyrefattribute.dita
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
- "reference.dtd">
-<reference id="theconkeyrefattribute" xml:lang="en-us">
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "concept.dtd">
+<concept id="theconkeyrefattribute" xml:lang="en-us">
 <title>The <xmlatt>conkeyref</xmlatt> attribute</title>
   <shortdesc>The <xmlatt>conkeyref</xmlatt> attribute provides an indirect content reference to
     topic elements, map elements, or elements within maps or topics. It allows the referencing
@@ -13,8 +13,7 @@
       </keywords>
     </metadata>
   </prolog>
-<refbody>
-    <section id="section-1">
+<conbody>
       <p>When the target of a content reference is an element within a topic or map, the value of
         the <xmlatt>conkeyref</xmlatt> attribute is a key name, followed by a slash ("/"), followed
         by the ID of the referenced element. The key name must be bound to the topic or map that
@@ -32,6 +31,6 @@
         by the <xmlatt>conrefend</xmlatt> attribute. See <xref
           keyref="attributes-conrefend/conkeyref"/> for more information and for examples of this
         behavior.</p>
-    </section>
-</refbody>
-</reference>
+
+</conbody>
+</concept>
diff --git a/specification/archSpec/base/theconrefattribute.dita b/specification/archSpec/base/theconrefattribute.dita
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
- "reference.dtd">
-<reference id="theconrefattribute" xml:lang="en-us">
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN"
+ "concept.dtd">
+<concept id="theconrefattribute" xml:lang="en-us">
 <title>The <xmlatt>conref</xmlatt> attribute</title>
 <shortdesc>The <xmlatt>conref</xmlatt> attribute is used to reference content that can be reused. It
     allows reuse of DITA elements, including topic or map level elements.</shortdesc>
@@ -12,16 +12,16 @@
       </keywords>
     </metadata>
   </prolog>
-<refbody>
-<section id="section-1"><p>The value of the <xmlatt>conref</xmlatt> attribute is a URI reference to a DITA element. See
+<conbody>
+<p>The value of the <xmlatt>conref</xmlatt> attribute is a URI reference to a DITA element. See
           <xref href="../../archSpec/base/uri-based-addressing.dita"/> for details on specifying URI
         references to DITA elements. As with other DITA references, a <xmlatt>conref</xmlatt>
         attribute that references a resource without an ID is treated as a reference to the first
         topic or map in the document.</p><note>When using the <xmlatt>conref</xmlatt> attribute on an element, the content of that element is
-        ignored. For example, if a phrase is marked up like
-        this:<codeblock>&lt;ph conref="#topic/ph">Something&lt;/ph></codeblock> the
-        word "Something" will be replaced by the content of the referenced
-          <xmlelement>ph</xmlelement> element.</note></section>
-</refbody>
-</reference>
+        ignored <ph rev="review-ella">by processors</ph>. For example, if a phrase is marked up like
+        this:<codeblock>&lt;ph conref="#topic/ph">Something&lt;/ph></codeblock> the word "Something"
+        will be replaced by the content of the referenced <xmlelement>ph</xmlelement>
+        element.</note>
+</conbody>
+</concept>
 
diff --git a/specification/archSpec/base/theconrefendattribute.dita b/specification/archSpec/base/theconrefendattribute.dita
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
-<reference id="theconrefendattribute" xml:lang="en-us">
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="theconrefendattribute" xml:lang="en-us">
   <title>The <xmlatt>conrefend</xmlatt> attribute</title>
   <shortdesc>The <xmlatt>conrefend</xmlatt> attribute is used when referencing a range of elements
     with the conref mechanism. The <xmlatt>conref</xmlatt> or <xmlatt>conkeyref</xmlatt> attribute
@@ -13,7 +13,7 @@
       </keywords>
     </metadata>
   </prolog>
-  <refbody>
+  <conbody>
     <section id="section-1"><title>Using <xmlatt>conref</xmlatt> together with
           <xmlatt>conrefend</xmlatt></title>
       <p>The following markup rules apply when using or implementing <xmlatt>conrefend</xmlatt>:<ul>
@@ -74,5 +74,5 @@
         the <xmlatt>conref</xmlatt> attribute itself is not present for fallback, the
           <xmlatt>conrefend</xmlatt> attribute is ignored.</p>
     </section>
-  </refbody>
-</reference>
+  </conbody>
+</concept>
diff --git a/specification/dita-2.0-specification-subjectScheme.ditamap b/specification/dita-2.0-specification-subjectScheme.ditamap
@@ -64,6 +64,7 @@
     <subjectdef keys="review-aretha"/>
     <subjectdef keys="review-chenier"/>
     <subjectdef keys="review-dave-alvin"/>
+    <subjectdef keys="review-ella"/>
     <subjectdef keys="2.0"/>
     <subjectdef keys="tc-review"/>
     <subjectdef keys="rendering">