Updates based on Review Dave Alvin

keberlein · Aug 26, 2024 · 90fa743 · 90fa743
1 parent 28cec49
commit 90fa743
Show file tree

Hide file tree

Showing 10 changed files with 75 additions and 62 deletions.
diff --git a/specification/archSpec/base/example-index-range-defined-in-a-topic-prolog.dita b/specification/archSpec/base/example-index-range-defined-in-a-topic-prolog.dita
@@ -29,7 +29,7 @@
     &lt;metadata>
       &lt;keywords>
         &lt;indexterm start="acct">accounting&lt;/indexterm>
-        <ph rev="review-chenier">&lt;indexterm end="acct">accounting&lt;/indexterm></ph>
+        <ph rev="review-dave-alvin">&lt;indexterm end="acct"/></ph>
       &lt;/keywords>
     &lt;/metadata>
   &lt;/prolog>

diff --git a/specification/archSpec/base/example-index-range-in-a-single-topic.dita b/specification/archSpec/base/example-index-range-in-a-single-topic.dita
@@ -1,17 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
 <concept id="example-index-range-in-a-single-topic">
-    <title>Example: Index range defined in a single topic</title>
-    <shortdesc>In this scenario, an index range is defined directly in the
-    body of a
-    topic.<!-- This strategy is useful for lengthy topics.--></shortdesc>
-    <conbody>
-        <p>In the following code sample, the index range begins at the
-      start of the second paragraph and continues to the beginning of the
-      last
-      paragraph.<!-- If the end element was not present, the index range would end at the end of the topic.--></p>
-        <!--<draft-comment author="Eliot Kimber" time="09 August 2019"><p>Again, I don't think the boundary rule is necessary or appropriate.</p></draft-comment>-->
-        <codeblock>&lt;topic id="accounting">
+  <title>Example: Index range defined in a single topic</title>
+  <shortdesc>In this scenario, an index range is defined directly in the
+    body of a topic.</shortdesc>
+  <conbody>
+    <p>In the following code sample, the index range begins at the start of
+      the second paragraph and continues to the beginning of the last
+      paragraph.</p>
+    <codeblock>&lt;topic id="accounting">
   &lt;title>Accounting regulations&lt;/title>
   &lt;body>
     &lt;p>Be ethical in your accounting.&lt;/p>
@@ -21,5 +18,5 @@
   &lt;/body>
   &lt;!-- Potential sub-topics -->
 &lt;/topic></codeblock>
-    </conbody>
+  </conbody>
 </concept>
diff --git a/specification/archSpec/base/index-elements.dita b/specification/archSpec/base/index-elements.dita
@@ -2,11 +2,12 @@
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
 <concept id="index-elements">
     <title>Index elements</title>
-    <shortdesc>The content of <xmlelement>indexterm</xmlelement> elements
-    provides the text for the entries in <ph rev="review-chenier">an
-      index</ph>. <xmlelement>indexterm</xmlelement> elements can be nested
-    to create <ph rev="review-chenier">additional levels of indexing, such
-      as</ph> secondary and tertiary index entries. </shortdesc>
+    <shortdesc>The <ph rev="review-dave-alvin">contents</ph> of
+      <xmlelement>indexterm</xmlelement> elements provides the text for the
+    entries in <ph rev="review-chenier">an index</ph>.
+      <xmlelement>indexterm</xmlelement> elements can be nested to create
+      <ph rev="review-chenier">additional levels of indexing, such as</ph>
+    secondary and tertiary index entries. </shortdesc>
     <prolog>
         <metadata>
             <keywords>
@@ -29,10 +30,11 @@
             <dlentry>
                 <dt><xmlelement>indexterm</xmlelement></dt>
                 <dd><ph rev="review-chenier">Defines a term or subject that
-            can contribute to an index.</ph> The <xmlatt>start</xmlatt> and
-            <xmlatt>end</xmlatt> attributes on the
-            <xmlelement>indexterm</xmlelement> element specify index
-          ranges.</dd>
+            can contribute to an index.</ph>
+          <ph rev="review-dave-alvin">Matching values of
+              <xmlatt>start</xmlatt> and <xmlatt>end</xmlatt> attributes on
+              <xmlelement>indexterm</xmlelement> elements can specify an
+            index range.</ph></dd>
             </dlentry>
             <dlentry>
                 <dt><xmlelement>index-see</xmlelement></dt>

diff --git a/specification/archSpec/base/index-overview.dita b/specification/archSpec/base/index-overview.dita
@@ -1,26 +1,29 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
-<topic id="indexoverview" rev="review-chenier">
-    <title>Index overview</title>
-    <shortdesc>DITA provides several elements to enable indexing. Whether and how an index is
-        rendered will vary based on implementation decisions and rendering formats.</shortdesc>
-    <body>
+<topic id="indexoverview">
+  <title>Index overview</title>
+  <shortdesc>DITA provides several elements to enable indexing. Whether and
+    how an index is rendered will vary based on implementation decisions
+    and rendering formats.</shortdesc>
+  <body>
     <p>Here are some definitions:</p>
     <ul>
       <li>An <term>index</term> is a mapping from
           <xmlelement>indexterm</xmlelement> elements to locations in the
         DITA content.</li>
-      <li>A <term>generated index</term> is a mapping of index terms to rendered locations.</li>
+      <li>A <term>generated index</term> is a mapping of index terms to
+        rendered locations.</li>
     </ul>
-        <p>While DITA provides several elements that support indexing, how those elements are used
-            will vary by implementation.</p>
-        <ul>
+    <p>While DITA provides several elements that support indexing, how
+      those elements are used will vary by implementation.</p>
+    <ul>
       <li>A publishing format like PDF might use a back-of-the-book style
         index with page numbers, which typically involves merging index
-        elements and rendering with page numbers.</li>
-      <li>Another publishing format might have no rendered index at all,
-        but instead use the index element content to help weight search
-        results.</li>
+        elements and <ph rev="review-dave-alvin">generating</ph> page
+        numbers.</li>
+      <li>Another publishing format might have no rendered index, but it
+        would instead use the content of index elements to help weight
+        search results.</li>
       <li>Some implementations might choose to supplement a generated index
         with additional content, such as treating a specialized
           <xmlelement>keyword</xmlelement> element as both normal content
@@ -29,29 +32,34 @@
         cases, based on either implementation capabilities or style
         preferences.</li>
     </ul>
-        <p>While DITA itself defines markup for indexing and specifies
-      exactly what point an <xmlelement>indexterm</xmlelement> refers to,
-      it cannot force DITA documents to use consistent patterns that work
-      for all formats. Implementations should consider what edge cases are
-      relevant and how to treat them when rendering.</p>
-        <p>The following list includes some of the conditions that
+    <p>While DITA defines markup for indexing and specifies exactly the
+      point to which an <xmlelement>indexterm</xmlelement> refers, it
+      cannot force DITA documents to use consistent patterns that work for
+      all formats. Implementations <ph rev="review-dave-alvin">should
+        consider edge cases and how to treat them.</ph></p>
+    <p>The following list includes some of the conditions that
       implementations might want to be aware of when considering how to
       generate an index:<ul>
-        <li>Index processors typically ignore leading or trailing
-          whitespace characters.</li>
+        <li>Index processors typically ignore leading <ph
+            rev="review-dave-alvin">and</ph> trailing whitespace
+          characters.</li>
         <li>Processors might want to treat two entries separately if they
-          are defined with different cases.</li>
+          are defined with different <ph rev="review-dave-alvin"
+            >capitalization</ph>.</li>
         <li>Processors need to determine how to handle nested markup, such
-          as <xmlelement>keyword</xmlelement>, within an index entry.</li>
+          as an <xmlelement>keyword</xmlelement>
+          <ph rev="review-dave-alvin">element that is located within an
+              <xmlelement>indexterm</xmlelement> element.</ph></li>
         <li>Because <xmlelement>index-see</xmlelement> is used to refer to
           a term that is used <i>instead of</i> the current entry,
           processors should consider how to handle a case where an index
           term is used both as a page locator and with an
-            <xmlelement>index-see</xmlelement> for redirection.</li>
-        <li>Similarly, processors should consider how to handle a case
-          where an index term is defined with both an
-            <xmlelement>index-see</xmlelement> and an
+            <xmlelement>index-see</xmlelement>
+          <ph rev="review-dave-alvin">element</ph> for redirection.</li>
+        <li>Similarly, processors should consider how to handle <ph
+            rev="review-dave-alvin">the</ph> case where an index term is
+          defined with both an <xmlelement>index-see</xmlelement> and an
             <xmlelement>index-see-also</xmlelement> element.</li>
       </ul></p>
-    </body>
+  </body>
 </topic>
diff --git a/specification/archSpec/base/index-ranges.dita b/specification/archSpec/base/index-ranges.dita
@@ -3,9 +3,11 @@
 <concept id="index-ranges">
     <title>Index ranges</title>
     <shortdesc>Authors can use the <xmlatt>start</xmlatt> and
-      <xmlatt>end</xmlatt> attributes on <xmlelement>indexterm</xmlelement>
-    elements to index <ph rev="review-chenier">an extended discussion</ph>.
-      <ph rev="review-chenier">The generated index entry reflects the span
+      <xmlatt>end</xmlatt> attributes on <ph rev="review-dave-alvin">a pair
+      of</ph>
+    <xmlelement>indexterm</xmlelement> elements to index <ph
+      rev="review-chenier">an extended discussion</ph>. <ph
+      rev="review-chenier">The generated index entry reflects the span
       between the two <xmlelement>indexterm</xmlelement> elements </ph>. </shortdesc>
     <prolog>
         <metadata>
@@ -21,12 +23,15 @@
         <xmlelement>indexterm</xmlelement> with a <xmlatt>start</xmlatt>
       attribute. <ph rev="review-1">This is called a <term
           rev="review-chenier">start-of-range element</term>.</ph></p>
-    <p rev="review-chenier">The end of an index range is indicated by an
+    <p>The end of an index range is indicated by an
         <xmlelement>indexterm</xmlelement> element with an
         <xmlatt>end</xmlatt> attribute with a value that matches the
         <xmlatt>start</xmlatt> attribute on the start element. <ph
         rev="review-1">This is called an <term rev="review-chenier"
-          >end-of-range element</term>.</ph></p>
+          >end-of-range element</term>.</ph>
+      <ph rev="review-dave-alvin">End-of-range element should contain no
+        content or nested elements.</ph>
+    </p>
         <p rev="review-chenier">The location of the
         <xmlelement>indexterm</xmlelement> elements determines how the span
       is defined:</p>

diff --git a/specification/archSpec/base/indexes.dita b/specification/archSpec/base/indexes.dita
@@ -2,6 +2,6 @@
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
 <concept xml:lang="en-us" id="indexes">
  <title>Indexes</title>
- <shortdesc>Processors can generate an index from the content of indexing elements.</shortdesc>
- <conbody/>
+ <shortdesc>Processors can generate <ph rev="review-dave-alvin"
+      >indexes</ph> from the content of indexing elements.</shortdesc>
 </concept>
diff --git a/specification/archSpec/base/indexes.ditamap b/specification/archSpec/base/indexes.ditamap
@@ -11,7 +11,6 @@
         <topicref href="index-ranges.dita"/>
         <topicref href="index-sorting.dita"/>
         <topicref href="examples-indexing.dita">
-            <topicref href="example-of-nested-indexterm-elements.dita"/>
             <topicref href="example-index-range-in-a-single-topic.dita"/>
             <topicref href="example-index-range-defined-in-a-topic-prolog.dita"/>
             <topicref href="example-index-range-defined-in-a-map.dita"/>

diff --git a/specification/archSpec/base/location-of-indexterm-elements.dita b/specification/archSpec/base/location-of-indexterm-elements.dita
@@ -26,9 +26,10 @@
             </dlentry>
             <dlentry rev="review-1">
                 <dt>Anywhere else in a DITA topic</dt>
-                <dd>An <xmlelement>indexterm</xmlelement> element that is located in a topic (and
-                    not the topic prolog) is a point reference to the location where the
-                        <xmlelement>indexterm</xmlelement> element occurs.</dd>
+                <dd>An <xmlelement>indexterm</xmlelement> element that is
+          located in a topic (and not <ph rev="review-dave-alvin">in</ph>
+          the topic prolog) is a point reference to the location where the
+            <xmlelement>indexterm</xmlelement> element occurs.</dd>
             </dlentry>
             <dlentry>
                 <dt>DITA maps</dt>

diff --git a/specification/dita-2.0-specification-subjectScheme.ditamap b/specification/dita-2.0-specification-subjectScheme.ditamap
@@ -63,6 +63,7 @@
     <subjectdef keys="review-t"/>
     <subjectdef keys="review-aretha"/>
     <subjectdef keys="review-chenier"/>
+    <subjectdef keys="review-dave-alvin"/>
     <subjectdef keys="2.0"/>
     <subjectdef keys="tc-review"/>
     <subjectdef keys="rendering">

diff --git a/specification/resources/DITA2.0-spec.ditaval b/specification/resources/DITA2.0-spec.ditaval
@@ -129,5 +129,5 @@
   <revprop action="flag" color="red" val="review-r"/>
   <revprop action="flag" color="red" val="review-s"/>
   <revprop action="flag" color="red" val="review-chenier"/>
-
+  <revprop action="flag" color="red" val="review-dave-alvin"/>
 </val>