Merge pull request #619 from keberlein/chunking-indexing

Edits to chunking topics

specification/archSpec/base/chunk-attribute-combine.dita

@@ -6,6 +6,15 @@
     <codeph>chunk="combine"</codeph> instructs a processor to combine the
       <ph rev="review-h">referenced</ph> source documents for rendering
     purposes. A single result document is generated.</shortdesc>
+  <prolog>
+    <metadata>
+      <keywords>
+        <indexterm>chunking<indexterm>processing</indexterm></indexterm>
+        <indexterm>processing<indexterm>chunk
+          attributes</indexterm></indexterm>
+      </keywords>
+    </metadata>
+  </prolog>
 <conbody>
         <p>The following rules apply:</p>
         <ul>
@@ -35,5 +44,8 @@
           <xmlatt>chunk</xmlatt> attributes on elements within the <ph
           rev="review-h">grouping</ph> are ignored.</li>
         </ul>
+    <draft-comment author="Kristen J Eberlein" time="04 February 2022">
+      <p>What's the difference between the content of li[3] and [li4]?</p>
+    </draft-comment>
 </conbody>
 </concept>

specification/archSpec/base/chunk-attribute-overview.dita

@@ -9,6 +9,18 @@
     the organization of source DITA documents has an effect on <ph
       rev="review-h">the</ph> organization of published
     documents.</shortdesc>
+  <prolog>
+    <metadata>
+      <keywords>
+        <indexterm>chunking<indexterm>attributes</indexterm></indexterm>
+        <indexterm>chunking<indexterm>normative
+          statements</indexterm></indexterm>
+        <indexterm>chunking<indexterm>overview</indexterm></indexterm>
+        <indexterm>normative
+          statements<indexterm>chunking</indexterm></indexterm>
+      </keywords>
+    </metadata>
+  </prolog>
 <conbody>
     <p rev="review-h">The <xmlatt>chunk</xmlatt> attribute only operates on
       topics and nested topics. It does not operate on other topic content,

specification/archSpec/base/chunk-attribute-split.dita

@@ -7,6 +7,15 @@
     topic from the referenced source document into its own document for
     rendering purposes. Multiple result documents are
     generated.</shortdesc>
+  <prolog>
+    <metadata>
+      <keywords>
+        <indexterm>chunking<indexterm>processing</indexterm></indexterm>
+        <indexterm>processing<indexterm>chunk
+          attributes</indexterm></indexterm>
+      </keywords>
+    </metadata>
+  </prolog>
 <conbody>
         <p>The following rules apply:</p>
         <ul>
@@ -28,5 +37,11 @@
           <codeph>combine</codeph> value is encountered, in which case
           <codeph>combine</codeph> takes over for that entire branch. </li>
         </ul>
+    <draft-comment author="Kristen J Eberlein" time="04 February 2022">
+      <p>What about <codeph>chunk="split" specified on a map reference or
+          map branch?</codeph></p>
+      <p>If possible, I'd like us to make this list and the one in the
+        previous topic parallel ...</p>
+    </draft-comment>
 </conbody>
 </concept>

specification/archSpec/base/example-chunk-combine-all.dita

@@ -4,20 +4,39 @@
 <title>Example: Using <xmlatt>chunk</xmlatt> to combine all documents into one</title>
 <shortdesc>When a processor would typically render each topic document as
     an independent result document, the <xmlatt>chunk</xmlatt> attribute
-    can be used to render all content as a single document.</shortdesc>
+    can be used to render all content as a single document.<draft-comment
+      author="Kristen J Eberlein" time="04 February 2022">
+      <p>Here's an alternate short description for us to consider: <q>When
+          a processor would typically render each topic document as an
+          independent result document, specifying
+            <codeph>chunk="combine</codeph> on the root map element
+          instructs the processor to render all content as a single
+          document.</q></p>
+    </draft-comment></shortdesc>
+  <prolog>
+    <metadata>
+      <keywords>
+        <indexterm>chunking<indexterm>examples<indexterm>combining all
+              documents</indexterm></indexterm></indexterm>
+        <indexterm>examples<indexterm><indexterm>chunking<indexterm>combining
+                all
+          documents</indexterm></indexterm></indexterm></indexterm>
+      </keywords>
+    </metadata>
+  </prolog>
 <conbody>
 <fig>
       <title>Root map and the topics that it references</title>
       <p>Consider the following DITA map:</p>
       <codeblock>&lt;map>
   &lt;title>Lesson plan&lt;/title>
   &lt;topicref href="background.dita">
-    &lt;!-- more background topics -->
+    &lt;!-- More <ph rev="review-h">topic references to</ph> background topics -->
   &lt;/topicref>
   &lt;topicref href="goals.dita">
-    &lt;!-- more goal topics -->
+    &lt;!-- More <ph rev="review-h">topic references to</ph> goal topics -->
   &lt;/topicref>
-  &lt;!-- more topics -->
+  &lt;!-- More <ph rev="review-h">topic references</ph> -->
 &lt;/map>
 </codeblock>
       <p>The following code samples show the content of
@@ -32,30 +51,31 @@
       <codeblock><b>&lt;!-- Content of goals.dita --></b>
 &lt;topic id="goals">
   &lt;title>Lesson <ph rev="review-h">goals</ph>&lt;/title>
-  &lt;shortdesc>After you complete the lesson, ...&lt;/shortdesc>
+  &lt;shortdesc>After you complete the lesson ...&lt;/shortdesc>
   &lt;body> &lt;!-- ... --> &lt;/body>
 &lt;/topic></codeblock>
     </fig>
-<p>For many systems or output formats, each document in the map is rendered
-      as an independent document. For example, rendering this map as HTML5
-      might result in <filepath>background.html</filepath> and
+<p>For many systems or output formats, each document in the map is <ph
+        rev="review-h">typically</ph> rendered as an independent document.
+      For example, rendering this map as HTML5 might result in
+        <filepath>background.html</filepath> and
         <filepath>goals.html</filepath>, in addition to other HTML5
       files.</p>
 <fig>
       <title>Root map with chunking specified</title>
       <p>If the output requirements demand only a single result document,
         specifying <codeph>chunk="combine"</codeph> on the root map element
         instructs a processor to render a single document that combines all
-        topics.</p>
+        topics:</p>
       <codeblock>&lt;map <b>chunk="combine"</b>>
   &lt;title>Lesson plan&lt;/title>
   &lt;topicref href="background.dita">
-    &lt;!-- more background topics -->
+    &lt;!-- More <ph rev="review-h">topic references to</ph> background topics -->
   &lt;/topicref>
   &lt;topicref href="goals.dita">
-    &lt;!-- more goal topics -->
+    &lt;!-- More <ph rev="review-h">topic references to</ph> goal topics -->
   &lt;/topicref>
-  &lt;!-- more topics -->
+  &lt;!-- More <ph rev="review-h">topic references</ph> -->
 &lt;/map></codeblock>
     </fig>
 <fig id="fig_fkg_dhd_1gb">
@@ -73,21 +93,21 @@
     &lt;title>Prerequisite concepts&lt;/title>
     &lt;shortdesc>This information is necessary before starting&lt;/shortdesc>
     &lt;body> ... &lt;/body>
-      &lt;!-- more background topics -->
+      &lt;!-- More background topics -->
   &lt;/topic>
   <b>&lt;!-- original content of goals.dita --></b>
   &lt;topic id="goals">
     &lt;title>Lesson <ph rev="review-h">goals</ph>&lt;/title>
-    &lt;shortdesc>After you complete the lesson, ...&lt;/shortdesc>
+    &lt;shortdesc>After you complete the lesson ...&lt;/shortdesc>
     &lt;body> ... &lt;/body>
-    &lt;!-- more goal topics -->
+    &lt;!-- More goal topics -->
   &lt;/topic>
-  &lt;!-- more topics -->
+   &lt;!-- More topics -->
 &lt;/dita></codeblock>
       <p><ph rev="review-h">The</ph> content from all topics within the map
         is combined into a single result <ph rev="review-h">document</ph>,
-        with a topic order and topic nesting structure that match the
-        original map hierarchy:</p>
+        with a topic order and topic nesting structure that <ph
+          rev="review-h">matches</ph> the original map hierarchy:</p>
 </fig>
 </conbody>
 </concept>

specification/archSpec/base/example-chunk-combine-branch.dita

@@ -6,23 +6,42 @@
 <shortdesc>When a publishing system typically would render each topic
     document as an independent result document, the <xmlatt>chunk</xmlatt>
     attribute can be used to render individual branches of a map as single
-    documents.</shortdesc>
+      documents.<draft-comment author="Kristen J Eberlein"
+      time="04 February 2022">
+      <p>Here's an alternate short description for us to consider: <q>When
+          a processor would typically render each topic document as an
+          independent result document, specifying
+            <codeph>chunk="combine</codeph> on a map branch instructs the
+          processor to render the content of the map branch as a single
+          document.</q></p>
+    </draft-comment></shortdesc>
+  <prolog>
+    <metadata>
+      <keywords>
+        <indexterm>chunking<indexterm>examples<indexterm>combining a map
+              branch</indexterm></indexterm></indexterm>
+        <indexterm>examples<indexterm><indexterm>chunking<indexterm>combining
+                a map
+          branch</indexterm></indexterm></indexterm></indexterm>
+      </keywords>
+    </metadata>
+  </prolog>
 <conbody>
 <fig>
       <title>Root map and the topics that it references</title>
       <p>Consider the following DITA map:</p>
       <codeblock>&lt;map>
   &lt;title>Lesson plan&lt;/title>
   &lt;topicref href="goals.dita">
-    &lt;!-- more goal topics -->
+    <ph rev="review-h">&lt;!-- More topic references to goal topics --></ph>
   &lt;/topicref>
   &lt;topicref href="firstLesson.dita">
-    &lt;!-- more tasks in the first lesson -->
+    <ph rev="review-h">&lt;!-- More topic references to first lesson topics --></ph>
   &lt;/topicref>
   &lt;topicref href="nextLesson.dita">
-    &lt;!-- more tasks in the next lesson -->
+    <ph rev="review-h">&lt;!-- More topic references to second lesson topics --></ph>
   &lt;/topicref>
-  &lt;!-- More branches -->
+  <ph rev="review-h">&lt;!-- More map branches --></ph>
 &lt;/map></codeblock>
     </fig>
     <p>The following code samples show the content of
@@ -31,18 +50,23 @@
     <codeblock><b>&lt;!-- firstLesson.dita --></b>
 &lt;task id="firstLesson">
   &lt;title>Starting to work with scissors&lt;/title>
-  &lt;shortdesc>This lesson will teach ...&lt;/shortdesc>
-  &lt;taskbody>&lt;!-- ... -->&lt;/taskbody>
+  &lt;shortdesc>This lesson will teach ... &lt;/shortdesc>
+  &lt;taskbody>
+    &lt;!-- ... -->
+  &lt;/taskbody>
 &lt;/task></codeblock>
     <codeblock><b>&lt;!-- nextLesson.dita --></b>
 &lt;task id="nextLesson">
   &lt;title>Advanced cutting&lt;/title>
-  &lt;shortdesc>This lesson will introduce <ph rev="review-h">complex</ph> shapes...&lt;/shortdesc>
-  &lt;taskbody>&lt;!-- ... -->&lt;/taskbody>
+  &lt;shortdesc>This lesson will introduce <ph rev="review-h">complex</ph> shapes ... &lt;/shortdesc>
+  &lt;taskbody>
+    &lt;!-- ... -->
+  &lt;/taskbody>
 &lt;/task></codeblock>
-<p>For many systems or output formats, each document in the map is rendered
-      as an independent document. For example, rendering this map as HTML5
-      might result in <filepath>goals.html</filepath>,
+<p>For many systems or output formats, each document in the map is <ph
+        rev="review-h">typically</ph>rendered as an independent document.
+      For example, rendering this map as HTML5 might result in
+        <filepath>goals.html</filepath>,
         <filepath>firstLesson.html</filepath>, and
         <filepath>nextLesson.html</filepath>, while the child documents
       within each branch would each result in their own HTML files.</p>
@@ -55,22 +79,22 @@
         processor to render one document that combines all topics in that
         branch.</p>
       <p>In the following code sample, <codeph>chunk="combine"</codeph> is
-        specified on the lesson branches. This indicates that each lesson
-        branch should rendered as a single result document<ph
-          rev="review-h">. Topics</ph> in the first branch with
-          <filepath>goals.dita</filepath> will not be affected.</p>
+        specified on the <ph>map branches for the lessons</ph>. This
+        indicates that each lesson branch should rendered as a single
+        result document<ph rev="review-h">. Topics</ph> in the first branch
+        with <filepath>goals.dita</filepath> will not be affected.</p>
       <codeblock>&lt;map>
   &lt;title>Lesson plan&lt;/title>
-  &lt;topicref href="goals.dita">
-    &lt;!-- more goal topics -->
+  &lt;topicref href="goals.dita" <b>chunk="combine"</b>>
+    <ph rev="review-h">&lt;!-- More topic references to goal topics --></ph>
   &lt;/topicref>
   &lt;topicref href="firstLesson.dita" <b>chunk="combine"</b>>
-    &lt;!-- more tasks in the first lesson -->
+    <ph rev="review-h">&lt;!-- More topic references to first lesson topics --></ph>
   &lt;/topicref>
-  &lt;topicref href="nextLesson.dita" <b>chunk="combine"</b>>
-    &lt;!-- more tasks in the next lesson -->
+  &lt;topicref href="nextLesson.dita">
+    <ph rev="review-h">&lt;!-- More topic references to second lesson topics --></ph>
   &lt;/topicref>
-  &lt;!-- More branches -->
+  <ph rev="review-h">&lt;!-- More map branches --></ph>
 &lt;/map></codeblock>
     </fig>
 <fig>
@@ -82,31 +106,35 @@
 &lt;map>
   &lt;title>Lesson plan&lt;/title>
   &lt;topicref href="goals.dita">
-    &lt;!-- more goal topics -->
+    <ph rev="review-h">&lt;!-- More topic references to goal topics --></ph>
   &lt;/topicref>
   &lt;topicref href="firstLesson.dita"/>
   &lt;topicref href="nextLesson.dita"/>
-  &lt;!-- More branches -->
+  &lt;!-- More map branches -->
 &lt;/map></codeblock>
       <codeblock><b>&lt;!-- firstLesson.dita --></b>
 &lt;task id="firstLesson">
   &lt;title>Starting to work with scissors&lt;/title>
-  &lt;shortdesc>This lesson will teach ...&lt;/shortdesc>
-  &lt;taskbody>&lt;!-- ... -->&lt;/taskbody>
-  <b>&lt;!-- more tasks in the first lesson --></b>
+  &lt;shortdesc>This lesson will teach ... &lt;/shortdesc>
+  &lt;taskbody>
+    &lt;!-- ... -->
+  &lt;/taskbody>
+  <b>&lt;!-- More first lesson topics --></b>
 &lt;/task></codeblock>
       <codeblock><b>&lt;!-- nextLesson.dita --></b>
 &lt;task id="nextLesson">
   &lt;title>Advanced cutting&lt;/title>
   &lt;shortdesc>This lesson will introduce <ph rev="review-h">complex</ph> shapes...&lt;/shortdesc>
-  &lt;taskbody>&lt;!-- ... -->&lt;/taskbody>
-  <b>&lt;!-- more tasks in the next lesson --></b>
+  &lt;taskbody>
+    &lt;!-- ... -->
+  &lt;/taskbody>
+  <b>&lt;!-- More second lesson topics --></b>
 &lt;/task></codeblock>
       <p>Content from each branch where <xmlatt>chunk</xmlatt> attribute is
-        specified is combined into a single result document, with an order
-        and topic nesting structure that matches the original map
-        hierarchy. Content from outside of those branches remains
-        unchanged.</p>
+        specified is combined into a single result document, with a <ph
+          rev="review-h">topic</ph> order and topic nesting structure that
+        matches the original map hierarchy. Content from outside of those
+        branches remains unchanged.</p>
     </fig>
 </conbody>
 </concept>