Merge pull request #935 from oasis-tcs/indexbranch

Updates from indexing review Clifton Chenier

specification/archSpec/base/example-index-range-defined-in-a-map.dita

@@ -2,8 +2,8 @@
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
 <concept id="example-index-range-defined-in-a-map">
     <title>Example: Index range defined in a map</title>
-    <shortdesc>In this scenario, an index range is defined in the DITA map. Ranges defined in a DITA
-        map can span peer topics.</shortdesc>
+    <shortdesc>In this scenario, an index range is defined in the DITA map.
+    Ranges defined in a DITA map can span topics.</shortdesc>
     <conbody>
         <p>Consider the following DITA map:</p>
         <codeblock>&lt;map>
@@ -20,24 +20,14 @@
   &lt;topicref href="pineapples.dita">
     &lt;topicmeta>
       &lt;keywords>
-        &lt;indexterm start="acme-fruit"/>
+        &lt;indexterm <ph rev="review-chenier">end</ph>="acme-fruit"/>
       &lt;/keywords>
     &lt;/topicmeta>
   &lt;/topicref>
   &lt;!-- ... -->
 &lt;/map></codeblock>
-        <p>The index range begins with the start of the first topic title in
-                <filepath>apples.dita</filepath>, and it continues until the end of the last element
-            in <filepath>pineapples.dita</filepath>. If an end element was not specified, the range
-            would continue to the end of the map.</p>
-    <draft-comment author="Eliot Kimber" time="09 August 2019">I think this should be a reportable
-      error or warning since it's almost certainly not the author's intent for a range to span to
-      the end of the publication.</draft-comment>
-    <draft-comment author="Kristen J Eberlein" time="13 August 2019">
-      <p>Eliot, I disagree. If the map is a submap that is consumed by a larger publication (for
-        example, a map of examples of using keys), I think the default range boundary of "end of the
-        map" might be entirely appropriate.</p>
-      <!--<p>Also, this is example is stating behavior about ranges defined in maps that we do not lay out in <xref href="index-ranges.dita"/> – in particular, that the presence of an end element in a map signifies that the end-of-the-range is the <b>end</b> of the topic that contains the end element. This makes good sense to me, but it conflicts with the usual expectation that an <xmlelement>indexterm</xmlelement> element in a map (or prolog) is a point reference to the start of the topic title.</p>-->
-    </draft-comment>
+        <p>The index range begins with the start of the first topic title
+      in <filepath>apples.dita</filepath>, and it continues until the end
+      of the last element in <filepath>pineapples.dita</filepath>.</p>
     </conbody>
 </concept>

specification/archSpec/base/example-index-range-defined-in-a-topic-prolog.dita

@@ -20,14 +20,16 @@
   <!-- ... -->
 &lt;/map></codeblock>
         <p>The information developer wants an index entry that will span
-                <filepath>acct.dita</filepath> and its children. He uses the following markup in
-                <filepath>acct.dita</filepath>:</p>
+        <filepath>acct.dita</filepath> and its children. <ph
+        rev="review-chenier">They use </ph>the following markup in
+        <filepath>acct.dita</filepath>:</p>
         <codeblock>&lt;topic id="accounting-at-acme">
   &lt;title>Accounting at Acme&lt;/title>
   &lt;prolog>
     &lt;metadata>
       &lt;keywords>
         &lt;indexterm start="acct">accounting&lt;/indexterm>
+        <ph rev="review-chenier">&lt;indexterm end="acct">accounting&lt;/indexterm></ph>
       &lt;/keywords>
     &lt;/metadata>
   &lt;/prolog>
@@ -36,20 +38,5 @@
         <p>This markup specifies that the index range begins with the start of the topic title, and
             the end of the range is the end of the <filepath>forms.dita</filepath> topic. The index
             range includes the "Accounting at Acme" topic and its two child topics.</p>
-        <p>The information developer could have included an end element (for example,
-                <codeph>&lt;indexterm end="acct"/></codeph>) in the topic prolog, but it is not
-            necessary. If the topic prolog had included an end element, the effective index range
-            would be identical.</p>
-        <draft-comment author="Eliot Kimber" time="09 August 2019">
-            <p>I think this rule has the same problem as for ending the range at topic body
-                boundaries: it means you couldn't start a range in one topic's prolog and end it in
-                the prolog of another sibling topic.</p>
-            <p>That would be a hard thing to manage so probably not a realistic use case, so I can
-                see an argument that prolog-defined ranges span the effective topic tree rooted at
-                the topic with the prolog. But there's no particular reason to impose the
-                constraint.</p>
-            <p>That is, a processor that can handle index ranges can also detect when a range is
-                started in a topic prolog but not ended in one and report the case.</p>
-        </draft-comment>
     </conbody>
 </concept>

specification/archSpec/base/example-index-range-in-a-single-topic.dita

@@ -2,12 +2,14 @@
 <!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>
+    <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>
+        <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">
   &lt;title>Accounting regulations&lt;/title>

specification/archSpec/base/example-of-nested-indexterm-elements.dita

@@ -5,6 +5,8 @@
   <shortdesc>This example contains a multilevel <xmlelement>indexterm</xmlelement>
     element.</shortdesc>
   <conbody>
+    <draft-comment author="Kristen J Eberlein" time="12 August 2024">Do we
+      want to keep or jettison this topic? Enhance it?</draft-comment>
     <p>Given the following <xmlelement>indexterm</xmlelement> elements:</p>
     <codeblock>&lt;indexterm>cheese
   &lt;indexterm>sheeps milk
@@ -16,7 +18,8 @@
     &lt;indexterm>chevre&lt;/indexterm>
   &lt;/indexterm>
 &lt;/indexterm></codeblock>
-    <p>A processor treats the <xmlelement>indexterm</xmlelement> elements as equivalent to the
+    <p>A processor <ph rev="review-chenier">might treat</ph> the
+        <xmlelement>indexterm</xmlelement> elements as equivalent to the
       following multilevel <xmlelement>indexterm</xmlelement> element:</p>
     <codeblock>&lt;indexterm>cheese
   &lt;indexterm>sheeps milk
@@ -26,8 +29,8 @@
     &lt;indexterm>chevre&lt;/indexterm>
   &lt;/indexterm>
 &lt;/indexterm></codeblock>
-    <!--<draft-comment author="Eliot Kimber" time="09 August 2019"><p>This example reflects a rule about how entries are merged to create effective index structures but per the discussion above, I don't think those rules have been stated with sufficient completeness.</p><p>The example is logical but it's not justified by reference to a previously-defined rule.</p></draft-comment>-->
-    <p>A processor generates the following index entries:</p>
+    <p>A processor <ph rev="review-chenier">might generate</ph> the
+      following index entries:</p>
     <ul>
       <li>A primary entry for "cheese"</li>
       <li>Secondary entries for "goats milk" and "sheeps milk"</li>

specification/archSpec/base/index-elements.dita

@@ -2,9 +2,11 @@
 <!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 a generated index. <xmlelement>indexterm</xmlelement> elements can be nested to
-        create secondary and tertiary index entries. </shortdesc>
+    <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>
     <prolog>
         <metadata>
             <keywords>
@@ -21,29 +23,34 @@
         </metadata>
     </prolog>
     <conbody>
-        <p>The following elements contain information that processors use to generate indexes.</p>
+        <p>The following elements contain information that processors <ph
+        rev="review-chenier">can</ph> use to generate indexes:</p>
         <dl>
             <dlentry>
                 <dt><xmlelement>indexterm</xmlelement></dt>
-                <dd>Instructs a processor to generate an index entry. The <xmlatt>start</xmlatt> and
-                        <xmlatt>end</xmlatt> attributes on the <xmlelement>indexterm</xmlelement>
-                    element can specify index ranges.</dd>
+                <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>
             </dlentry>
             <dlentry>
                 <dt><xmlelement>index-see</xmlelement></dt>
-                <dd rev="review-1">Instructs a processor to generate a <term>see reference</term>.
-                    See references direct a reader to the preferred term.</dd>
+                <dd rev="review-1"><ph rev="review-chenier">Defines a term or subject to use as a
+                            <term>see reference</term>.</ph> See references direct a reader to the
+                    preferred term.</dd>
             </dlentry>
             <dlentry>
                 <dt><xmlelement>index-see-also</xmlelement></dt>
-                <dd rev="review-1">Instructs a processor to generate a <term>see also
-                        reference</term>. See also references direct a reader to an alternate index
-                    entry for additional information.</dd>
+                <dd rev="review-1"><ph rev="review-chenier">Defines a term or subject to use as a
+                            <term>see also reference</term>.</ph> See also references direct a
+                    reader to an alternate index entry for additional information.</dd>
             </dlentry>
         </dl>
-        <p>How the index elements are combined, the location of <xmlelement>indexterm</xmlelement>
-            elements, and the hierarchy of the DITA maps all affect how the index elements are
-            processed and the resulting generated index entries.</p>
-        <!--<draft-comment author="Joyce Lam" time="09 August 2019"><p>For clarity, I recommend writing this using an unordered list.</p><p>How the index elements are processed and the resulting generated index entries are effected by</p><ul><li>how the index elements are combined</li><li>the location of &lt;indexterm> elements, and</li><li>the hierarchy of the DITA maps.</li></ul></draft-comment>-->
+        <p>How the index elements are combined, the location of
+        <xmlelement>indexterm</xmlelement> elements, and the hierarchy of
+      the DITA maps all <ph rev="review-chenier">affect</ph> how the index
+      elements are processed and the <ph rev="review-chenier">index entries
+        that are generated</ph>.</p>
     </conbody>
 </concept>

specification/archSpec/base/index-overview.dita

@@ -0,0 +1,57 @@
+<?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>
+    <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>
+    </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>
+      <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
+        and an index entry.</li>
+      <li>Implementations might have different ways to render indexing edge
+        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
+      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>Processors might want to treat two entries separately if they
+          are defined with different cases.</li>
+        <li>Processors need to determine how to handle nested markup, such
+          as <xmlelement>keyword</xmlelement>, within an index entry.</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-also</xmlelement> element.</li>
+      </ul></p>
+    </body>
+</topic>

specification/archSpec/base/index-page-references.dita

@@ -2,8 +2,10 @@
 <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
 <concept id="index-page-references">
     <title>Index locators</title>
-    <shortdesc>Typically, an <xmlelement>indexterm</xmlelement> element instructs a processor to
-        generate an index entry with a locator.</shortdesc>
+    <shortdesc>An <xmlelement>indexterm</xmlelement> element <ph
+      rev="review-chenier">binds the content of the element, typically a
+      term or subject, to a specific location in a
+    document.</ph></shortdesc>
     <prolog>
         <metadata>
             <keywords>
@@ -12,19 +14,21 @@
         </metadata>
     </prolog>
     <conbody>
-        <p>The nesting of <xmlelement>indexterm</xmlelement> elements and the presence of
-                <xmlelement>index-see</xmlelement> elements determines whether locators are rendered
-            in the generated index entries:</p>
+        <p>The nesting of <xmlelement>indexterm</xmlelement> elements and
+      the presence of <xmlelement>index-see</xmlelement> elements
+      determines whether locators are rendered in generated <ph
+        rev="review-chenier">indexes</ph>:</p>
         <ul>
             <li>An <xmlelement>indexterm</xmlelement> element that does not contain child
                     <xmlelement>indexterm</xmlelement> elements (or an
                     <xmlelement>index-see</xmlelement> element) contributes a locator to the
                 generated index entry.</li>
-            <li>An <xmlelement>indexterm</xmlelement> element that contains child
-                    <xmlelement>indexterm</xmlelement> elements contributes to the hierarchy of the
-                multilevel index entry that is generated. Only the final nested
-                    <xmlelement>indexterm</xmlelement> element contributes a locator to the
-                generated index entry.</li>
+            <li>An <xmlelement>indexterm</xmlelement> element that contains
+        child <xmlelement>indexterm</xmlelement> elements contributes to
+        the hierarchy of the multilevel index entry that is generated. Only
+        a <ph rev="review-chenier">leaf</ph>
+        <xmlelement>indexterm</xmlelement> element contributes a locator to
+        the generated index entry.</li>
             <li>If an <xmlelement>indexterm</xmlelement> element also contains one or more
                     <xmlelement>index-see</xmlelement> elements, <ph rev="review-1">no locator is
                     included in the generated index entry.</ph></li>