Example: Using @chunk to render a single document from one or more branches

When a publishing system typically would render each topic document as an independent result document, the @chunk attribute can be used to render individual branches of a map as single documents.

Figure 1. Root map and the topics that it references

Consider the following DITA map:

<map>
  <title>Lesson plan</title>
  <topicref href="goals.dita">
    <!-- More topic references to goal topics -->
  </topicref>
  <topicref href="firstLesson.dita">
    <!-- More topic references to first lesson topics -->
  </topicref>
  <topicref href="nextLesson.dita">
    <!-- More topic references to second lesson topics -->
  </topicref>
  <!-- More map branches -->
</map>

The following code samples show the content of firstLesson.dita and nextLesson.dita:

<!-- firstLesson.dita -->
<task id="firstLesson">
  <title>Starting to work with scissors</title>
  <shortdesc>This lesson will teach ... </shortdesc>
  <taskbody>
    <!-- ... -->
  </taskbody>
</task>
<!-- nextLesson.dita -->
<task id="nextLesson">
  <title>Advanced cutting</title>
  <shortdesc>This lesson will introduce complex shapes ... </shortdesc>
  <taskbody>
    <!-- ... -->
  </taskbody>
</task>

For many systems or output formats, each document in the map is typicallyrendered as an independent document. For example, rendering this map as HTML5 might result in goals.html, firstLesson.html, and nextLesson.html, while the child documents within each branch would each result in their own HTML files.

Figure 2. Root map with chunking specified for certain branches

When output requirements demand that portions of the map be combined into a single document, specifying chunk="combine" on a map branch instructs a processor to render one document that combines all topics in that branch.

In the following code sample, chunk="combine" is specified on the map branches for the lessons. This indicates that each lesson branch should rendered as a single result document. Topics in the first branch with goals.dita will not be affected.

<map>
  <title>Lesson plan</title>
  <topicref href="goals.dita">
    <!-- More topic references to goal topics -->
  </topicref>
  <topicref href="firstLesson.dita" chunk="combine">
    <!-- More topic references to first lesson topics -->
  </topicref>
  <topicref href="nextLesson.dita">
    <!-- More topic references to second lesson topics -->
  </topicref>
  <!-- More map branches -->
</map>
Figure 3. Equivalent content of source documents after evaluation

The result of evaluating this @chunk attribute is equivalent to the following map and topic documents:

<!-- Root map -->
<map>
  <title>Lesson plan</title>
  <topicref href="goals.dita">
    <!-- More topic references to goal topics -->
  </topicref>
  <topicref href="firstLesson.dita"/>
  <topicref href="nextLesson.dita"/>
  <!-- More map branches -->
</map>
<!-- firstLesson.dita -->
<task id="firstLesson">
  <title>Starting to work with scissors</title>
  <shortdesc>This lesson will teach ... </shortdesc>
  <taskbody>
    <!-- ... -->
  </taskbody>
  <!-- More first lesson topics -->
</task>
<!-- nextLesson.dita -->
<task id="nextLesson">
  <title>Advanced cutting</title>
  <shortdesc>This lesson will introduce complex shapes...</shortdesc>
  <taskbody>
    <!-- ... -->
  </taskbody>
  <!-- More second lesson topics -->
</task>

Content from each branch where @chunk attribute is specified is combined into a single result document, with a topic order and topic nesting structure that matches the original map hierarchy. Content from outside of those branches remains unchanged.