Chunking examples

The following examples cover many common chunking scenarios, such as splitting one document into many rendered objects or merging many documents into one rendered object.

In the examples below, an extension of ".xxxx" is used in place of the actual extensions that will vary by output format. For example, when the output format is HTML, the extension might actually be ".html", but this is not required.

The examples below assume the existence of the following files:

parent1.dita, parent2.dita, etc., each containing a single topic with id P1, P2, etc.
child1.dita, child2.dita, etc., each containing a single topic with id C1, C2, etc.
grandchild1.dita, grandchild2.dita, etc., each containing a single topic with id GC1, GC2, etc.
nested1.dita, nested2.dita, etc., each containing two topics: parent topics with id N1, N2, etc., and child topics with ids N1a, N2a, etc.

ditabase.dita, with the following contents:

<dita xml:lang="en-us">
  <topic id="X">
    <title>Topic X</title><body><p>content</p></body>
  </topic>
  <topic id="Y">
    <title>Topic Y</title><body><p>content</p></body>
    <topic id="Y1">
      <title>Topic Y1</title><body><p>content</p></body>
      <topic id="Y1a">
       <title>Topic Y1a</title><body><p>content</p></body>
      </topic>
    </topic>
    <topic id="Y2">
      <title>Topic Y2</title><body><p>content</p></body>
    </topic>
  </topic>
  <topic id="Z">
    <title>Topic Z</title><body><p>content</p></body>
    <topic id="Z1">
      <title>Topic Z1</title><body><p>content</p></body>
    </topic>
  </topic>
</dita>

The following map causes the entire map to generate a single output chunk.

<map chunk="to-content"> 
   <topicref href="parent1.dita"> 
      <topicref href="child1.dita"/> 
      <topicref href="child2.dita"/> 
   </topicref> 
</map>

The following map will generate a separate chunk for every topic in every document referenced by the map. In this case, it will result in the topics P1.xxxx, N1.xxxx, and N1a.xxxx.
```
<map chunk="by-topic"> 
   <topicref href="parent1.dita"> 
      <topicref href="nested1.dita"/> 
   </topicref> 
</map> 
```

The following map will generate two chunks: parent1.xxxx will contain only topic P1, while child1.xxxx will contain topic C1, with topics GC1 and GC2 nested within C1.

<map> 
   <topicref href="parent1.dita"> 
      <topicref href="child1.dita" chunk="to-content"> 
        <topicref href="grandchild1.dita"/>
        <topicref href="grandchild2.dita"/>
      </topicref>
   </topicref> 
</map>

The following map breaks down portions of ditabase.dita into three chunks. The first chunk Y.xxxx will contain only the single topic Y. The second chunk Y1.xxxx will contain the topic Y1 along with its child Y1a. The final chunk Y2.xxxx will contain only the topic Y2. For navigation purposes, the chunks for Y1 and Y2 are still nested within the chunk for Y.

<map>
  <topicref href="ditabase.dita#Y" copy-to="Y.dita"
            chunk="to-content select-topic">
    <topicref href="ditabase.dita#Y1" copy-to="Y1.dita"
              chunk="to-content select-branch"/>
    <topicref href="ditabase.dita#Y2" copy-to="Y2.dita"
              chunk="to-content select-topic"/>
  </topicref>
</map>

The following map will produce a single output chunk named parent1.xxxx, containing topic P1, with topic Y1 nested within P1, but without topic Y1a.

<map chunk="by-document"> 
   <topicref href="parent1.dita" chunk="to-content"> 
      <topicref href="ditabase.dita#Y1" 
         chunk="select-topic"/> 
   </topicref> 
</map>

The following map will produce a single output chunk, parent1.xxxx, containing topic P1, topic Y1 nested within P1, and topic Y1a nested within Y1.

<map chunk="by-document"> 
   <topicref href="parent1.dita" chunk="to-content"> 
      <topicref href="ditabase.dita#Y1" 
         chunk="select-branch"/> 
   </topicref> 
</map>

The following map will produce a single output chunk, P1.xxxx. The topic P1 will be the root topic, and topics X, Y, and Z (together with their descendents) will be nested within topic P1.
```
<map chunk="by-topic"> 
   <topicref href="parent1.dita" chunk="to-content"> 
      <topicref href="ditabase.dita#Y1" 
         chunk="select-document"/> 
   </topicref> 
</map> 
```

The following map will produce a single output chunk named parentchunk.xxxx containing topic P1 at the root. Topic N1 will be nested within P1, and N1a will be nested within N1.

<map chunk="by-document"> 
   <topicref href="parent1.dita" chunk="to-content" copy-to="parentchunk.dita"> 
      <topicref href="nested1.dita" chunk="select-branch"/> 
   </topicref> 
</map>

The following map will produce two output chunks. The first chunk named parentchunk.xxxx will contain the topics P1, C1, C3, and GC3. The "to-content" token on the reference to child2.dita causes that branch to begin a new chunk named child2chunk.xxxx, which will contain topics C2 and GC2.

<map chunk="by-document"> 
   <topicref href="parent1.dita" 
      chunk="to-content" copy-to="parentchunk.dita"> 
      <topicref href="child1.dita" chunk="select-branch"/> 
      <topicref href="child2.dita" 
         chunk="to-content select-branch" 
         copy-to="child2chunk.dita"> 
         <topicref href="grandchild2.dita"/> 
      </topicref> 
      <topicref href="child3.dita"> 
         <topicref href="grandchild3.dita" 
            chunk="select-branch"/> 
      </topicref> 
   </topicref> 
 </map>

The following map produces a single chunk named nestedchunk.xxxx, which contains topic N1 with no topics nested within.

<map> 
   <topicref href="nested1.dita#N1" 
             copy-to="nestedchunk.dita" 
             chunk="to-content select-topic"/> 
</map>

In DITA 1.3, the "to-navigation" chunk is deprecated. In earlier releases, the following map produced two navigation chunks, one for P1, C1, and the other topic references nested under parent1.dita, and a second for P2, C2, and the other topic references nested under parent2.dita.

<map> 
    <topicref href="parent1.dita" 
          navtitle="How to set up a web server"
          chunk="to-navigation"> 
       <topicref href="child1.dita" 
          chunk="select-branch"/> 
       <!-- ... -->
    </topicref> 
    <topicref href="parent2.dita" 
          navtitle="How to ensure database security"
          chunk="to-navigation"> 
       <topicref href="child2.dita" 
          chunk="select-branch"/> 
       <!-- ... -->
    </topicref> 
    <!-- ... -->
</map>