Review comment updates to indexing topics

robander · Jul 20, 2024 · dae50cf · dae50cf
1 parent b81760f
commit dae50cf
Show file tree

Hide file tree

Showing 4 changed files with 59 additions and 39 deletions.
diff --git a/specification/archSpec/base/index-elements.dita b/specification/archSpec/base/index-elements.dita
@@ -4,7 +4,8 @@
     <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>
+        create <ph rev="review-chenier">additional levels of indexing, such as</ph> secondary and
+        tertiary index entries. </shortdesc>
     <prolog>
         <metadata>
             <keywords>
@@ -21,29 +22,30 @@
         </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 can 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>-->
     </conbody>
 </concept>
diff --git a/specification/archSpec/base/index-overview.dita b/specification/archSpec/base/index-overview.dita
@@ -0,0 +1,44 @@
+<?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>
+        <draft-comment author="rodaande">Placeholder for definition of "index" and "generated
+            index", as used within the DITA specification</draft-comment>
+        <p>While DITA provides several elements that support indexing, how those elements are used
+            will vary by implementation.</p>
+        <ul id="ul_vmb_tw3_1cc">
+            <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 index
+            term 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 id="ul_pxb_wdj_1cc">
+                <li>Index procssors 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 as a page locater but is also used
+                    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>.</li>
+            </ul></p>
+    </body>
+</topic>
diff --git a/specification/archSpec/base/indexes.dita b/specification/archSpec/base/indexes.dita
@@ -3,32 +3,5 @@
 <concept xml:lang="en-us" id="indexes">
  <title>Indexes</title>
  <shortdesc>Processors can generate an index from the content of indexing elements.</shortdesc>
- <conbody>
-  <draft-comment author="Kristen J Eberlein" time="09 August 2019">
-   <p>Comment by Eliot Kimber:</p>
-   <p>I think we need a general discussion of index processing and rendering that covers:</p>
-   <ul>
-    <li>Generation of page numbers or other locators (addresses "typical" question)</li>
-    <li>General rules or expectations for merging entries to produce the "effective index
-     markup"</li>
-    <li>General guidance for reporting conditions such as see-also references to non-existent
-     entries and missing @end for @start specified in maps.</li>
-   </ul>
-   <p>The current writeup reflects a lot of unstated assumptions about how index processing does or
-    should work, obviously reflecting how IBM's tools worked (and work today). These assumptions
-    need to be surfaced.</p>
-  </draft-comment>
-  <draft-comment author="Kristen J Eberlein" time="12 August 2019">
-   <p>We need to clearly state our assumptions, but I think we need to be careful about specifying
-    expected processing too precisely:</p>
-   <ul>
-    <li>We have no idea what output format people are transforming their DITA to; we cannot assume
-     that it is print-based. And we have no idea what sort of output formats might emerge after DITA
-     2.0 is released!</li>
-    <li>Not all DITA processors support indexing.</li>
-   </ul>
-   <p>It would be good to be upfront about the fact that many details about index generation will be
-    implementation specific.</p>
-  </draft-comment>
- </conbody>
+ <conbody/>
 </concept>
diff --git a/specification/archSpec/base/indexes.ditamap b/specification/archSpec/base/indexes.ditamap
@@ -3,6 +3,7 @@
 <map>
     <title>Indexes</title>
     <topicref href="indexes.dita">
+        <topicref href="index-overview.dita"/>
         <topicref href="index-elements.dita"/>
         <topicref href="location-of-indexterm-elements.dita"/>
         <topicref href="index-page-references.dita"/>