Chunking

Content often needs to be delivered in a different granularity than it is authored. The @chunk attribute enables map authors to specify that multiple source documents should be combined into a single document for delivery or that a single source document should be split into multiple documents for delivery.

About the @chunk attribute

The @chunk attribute specifies how a processor should split or combine source DITA documents into alternate organizational schemes for rendering purposes. This means that the @chunk attribute is only relevant when the organization of source DITA documents has an effect on the organization of published documents.

The @chunk attribute only operates on topics and nested topics. It does not operate on other topic content, such as sections.

The @chunk attribute is composed of a single token without any white space. DITA defines the following tokens for the @chunk attribute:

combine
Instructs a processor to combine the referenced source documents for rendering purposes. This is intended for cases where a publishing process normally results in a single output artifact for each source XML document.
split
Instructs a processor to split each topic from the referenced source document into its own document for rendering purposes. This is intended for cases where a publishing process normally results in a single output artifact for each source XML document, regardless of how many DITA topics exist within each source document.

Applications can use custom tokens for the @chunk attribute.

The @chunk attribute does not cascade.

The following rules apply to all values of the @chunk attribute:
  • When the source document organization has no effect on published output, such as when producing a single PDF or EPUB, processors MAY ignore the @chunk attribute.
  • When the @chunk attribute results in more or fewer documents based on the combine or split tokens, the hierarchy of topics within the resulting map and topic organization SHOULD match the hierarchy in the original topics and maps.
  • When the @chunk attribute results in more or fewer documents, processors MAY create their own naming schemes for those reorganized documents.
  • The @chunk attribute values apply to DITA topic documents referenced from a map. Processors MAY apply equivalent processing to non-DITA documents.

Processing chunk="combine"

The presence of chunk="combine" instructs a processor to combine the referenced source documents for rendering purposes.

The following rules apply:

  • When chunk="combine" is specified on the root element of a map, all source DITA documents that are referenced by the map are treated as one DITA document.
  • When chunk="combine" is specified on a branch of a map, all source DITA documents that are referenced within that branch are treated as one DITA document.
    Note (non-normative):
    This is true regardless of whether the element that specifies @chunk refers to a topic or specifies a heading. In cases such as <topicgroup> where a grouping element specifies chunk="combine", the equivalent DITA document would be a single DITA document with a root element that groups peer topics.
  • When chunk="combine" is specified on a map, map branch, or map reference, all source DITA documents that are grouped by the reference are treated as a single resource. Any additional @chunk attributes on elements within the grouping are ignored.

Processing chunk="split"

The presence of chunk="split" instructs a processor to split each topic from the referenced source document into its own document for rendering purposes.

The following rules apply:

  • When chunk="split" is specified on the root element of a map, it sets a default operation for all source DITA documents in the navigation structure of the map. The default split value is used except where a combine value is encountered, in which case combine takes over for that entire branch.
  • When chunk="split" is specified on a <topicref> element that references a source DITA document, it indicates that all topics within the referenced document should be rendered as individual documents.
  • When chunk="split" is specified on an element such as <topicgroup> that does not reference a source DITA document or result in published output, the attribute has no meaning.

Using the @chunk attribute for other purposes

Applications can define additional tokens for use in the @chunk attribute. These tokens are implementation dependent and might not be supported by other applications.

Examples of the @chunk attribute

This section is non-normative.

These examples illustrate the processing expectations for various scenarios that involve the @chunk attribute. The processing examples use either before and after sample markup or expanded syntax that shows the equivalent markup without the @chunk attribute.

Note (non-normative):
The examples use sample files with modified file names to help illustrate the equivalent before and after resolution of @chunk attributes. However, there is no requirement for implementations processing the @chunk attribute to generate files, as long as the rendered result is split or combined as described. If generating files, the file names are implementation dependent.

Example: Using @chunk to combine all documents into one

This section is non-normative.

When a processor would typically render each topic document as an independent result document, the @chunk attribute can be used to render all content as a single result document.

Figure 1. Root map and the topics that it references

Consider the following DITA map:

<map>
  <title>Lesson plan</title>
  <topicref href="background.dita">
    <!-- More topic references to background topics -->
  </topicref>
  <topicref href="goals.dita">
    <!-- More topic references to goal topics -->
  </topicref>
  <!-- More topic references -->
</map>

The following code samples show the content of background.dita and goals.dita:

<!-- Content of background.dita -->
<topic id="background">
  <title>Prerequisite concepts</title>
  <shortdesc>This information is necessary before starting ...</shortdesc>
  <body> <!-- ... --> </body>
</topic>
<!-- Content of goals.dita -->
<topic id="goals">
  <title>Lesson goals</title>
  <shortdesc>After you complete the lesson ...</shortdesc>
  <body> <!-- ... --> </body>
</topic>

For many systems or output formats, each document in the map is typically rendered as an independent document. For example, rendering this map as HTML5 might result in background.html and goals.html, in addition to other HTML5 files.

Figure 2. Root map with chunking specified

If the output requirements demand only a single result document, specifying chunk="combine" on the root map element instructs a processor to render a single document that combines all topics:

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

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

<!-- Root map -->
<map>
  <title>Lesson plan</title>
  <topicref href="combinedTopics.dita"/>
</map>
<dita>
  <!-- original content of background.dita -->
  <topic id="background">
    <title>Prerequisite concepts</title>
    <shortdesc>This information is necessary before starting</shortdesc>
    <body> <!-- ... --> </body>
      <!-- More background topics -->
  </topic>
  <!-- original content of goals.dita -->
  <topic id="goals">
    <title>Lesson goals</title>
    <shortdesc>After you complete the lesson ...</shortdesc>
    <body> <!-- ... --> </body>
    <!-- More goal topics -->
  </topic>
  <!-- More topics -->
</dita>

The content from all topics within the map is combined into a single result document, with a topic order and topic nesting structure that matches the original map hierarchy:

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

This section is non-normative.

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 4. 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 5. 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 6. 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.

Example: Using @chunk to combine groups of topics

This section is non-normative.

The @chunk attribute can be used on grouping elements to combine multiple source documents into one result document.

Figure 7. Root map with @chunk specified on grouping elements

Consider the following DITA map, where @chunk is specified on both <topicgroup> and <topichead> elements:

<map>
  <title>Groups are combined</title>
  <topicgroup chunk="combine">
    <topicref href="ingroup1.dita"/>
    <topicref href="ingroup2.dita"/>
  </topicgroup>
  <topichead chunk="combine">
    <topicmeta>
      <navtitle>Heading for a branch</navtitle>
    </topicmeta>
    <topicref href="inhead1.dita"/>
    <topicref href="inhead2.dita"/>
  </topichead>
</map>

The result of evaluating the @chunk attribute on the <topicgroup> element is equivalent to a single DITA document that contains the content of both ingroup1.dita and ingroup2.dita.

The result of evaluating the @chunk attribute on <topichead> is also a single result document. In many applications, a <topichead> is equivalent to a single title-only topic. In that case, the chunked result is equivalent to a root topic with the title "Heading for a branch", that contains as child topics the content of both inhead1.dita and inhead2.dita. If <topichead> is ignorable in the current processing context, the chunked result would be equivalent to processing <topicgroup>: a single DITA document with the content of both inhead1.dita and inhead2.dita.

Figure 8. Equivalent content of source documents after evaluation

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

<map>
  <title>Groups are combined</title>
  <topicref href="chunkgroup-1.dita"/>
  <topicref href="chunkgroup-2.dita"/>
</map>

The following code blocks show the content of chunkgroup-1.dita and chunkgroup-2.dita:

<!-- chunkgroup-1.dita -->
<dita>
  <!-- Content of ingroup1.dita -->
  <!-- Content of ingroup2.dita -->
</dita>
<!-- chunkgroup-2.dita -->
<dita>
  <topic id="head">
    <title>Heading for a branch</title>
    <!-- Content of inhead1.dita -->
    <!-- Content of inhead2.dita -->
  </topic>
</dita>

Example: How chunk="combine" effects the map hierarchy

This section is non-normative.

Special attention is necessary when combining a nested map hierarchy that includes documents with their own nested topics.

Figure 9. Source DITA map

Consider the following DITA map:

<map chunk="combine">
  <title>Generation example</title>
  <topicref href="ancestor.dita">
    <topicref href="middle.dita">
      <topicref href="child.dita"/>
    </topicref>
  </topicref>
</map>

In this case, the @chunk attribute instructs a processor to treat the three topics as a single combined document, while preserving the original map hierarchy.

Figure 10. Source documents with nested structures

Now consider the following three source documents, each of which includes nested or peer topics: ancestor.dita, middle.dita, and child.dita.

<!-- ancestor.dita -->
<dita>
  <topic id="ancestor-first">
    <title>First major topic in ancestor composite document</title>
    <!-- ... Topic content ... -->
  </topic>
  <!-- More topics in ancestor composite document -->
  <topic id="ancestor-last">
    <title>Last major topic in ancestor composite doc</title>
    <!-- ... Topic content ... -->
    <topic id="ancestor-last-child">
      <title>Child of last major topic in ancestor composite document</title>
      <!-- ... Topic content ... -->
    </topic>
  </topic>
</dita>
<!-- middle.dita -->
<topic id="middle-root">
  <title>Root topic in middle document</title>
  <body>
    <!-- ... -->
  </body>
  <topic id="middle-child">
    <title>Child of root topic in middle document</title>
    <!-- ... Body content, maybe more children topics -->
  </topic>
</topic>
<!-- child.dita -->
<topic id="child">
  <title>Small child topic</title>
  <!-- ... Topic content ... -->
</topic>
Figure 11. Evaluating chunk="combine"

When chunk="combine" is evaluated, the three source documents are combined into one. Both the ancestor and middle documents have child topics that need to be taken into account:

  • ancestor.dita has a root <dita> element, with several root-level topics. After evaluating the @chunk attribute, content from middle.dita is placed after the topic with id="ancestor-last-child"in ancestor.dita.
  • middle.dita does not have a <dita> element, but it does have a nested topic, so content from child.dita is located after that nested topic.

In each case, the original map hierarchy is preserved.

Figure 12. Equivalent content of source documents after evaluation

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

<!-- Root map -->
<map>
  <title>Generation example</title>
  <topicref href="input.dita"/>
</map>
<!-- input.dita -->
<dita>
  <topic id="ancestor-first">
    <title>First major topic in ancestor composite doc</title>
    <!-- ... Topic content ... -->
  </topic>
  <!-- More topics in ancestor composite doc -->
  <topic id="ancestor-last">
    <title>Last major topic in ancestor composite doc</title>
    <!-- ... Topic content ... -->
    <topic id="ancestor-last-child">
      <title>Child of last major topic in ancestor composite doc</title>
      <!-- ... Topic content ... -->
    </topic>
    <!-- Content of middle.dita combined here -->
    <topic id="middle-root">
      <title>Root topic in middle doc</title>
      <body><!-- ... --></body>
      <topic id="middle-child">
        <title>Child of root topic in middle doc</title>
        <!-- ... Body content, maybe more children topics ... -->
      </topic>
      <!-- Content of child.dita combined here -->
      <topic id="child">
        <title>Small child topic</title>
        <!-- ... Topic content ... -->
      </topic>
    </topic>
  </topic>
</dita>

Example: Using @chunk to split documents

This section is non-normative.

When topics are authored or generated in a single DITA document, specifying chunk="split" instructs processors to render them individually when possible.

This topic contains two examples: Splitting a single topic document and splitting all topic documents.

Splitting a single topic document

This section is non-normative.

This example covers the scenario of splitting a single topic document that is referenced in a DITA map.

Example 13. Root map and the topic documents that it references

Consider the following DITA map, which references generated topics that document the messages that are produced by an application:

<map>
  <title>Message guide</title>
  <topicref href="about.dita">
    <topicref href="messages-install.dita"/>
    <topicref href="messages-run.dita"/>
    <topicref href="messages-other.dita"/>
  </topicref>
</map>

The following code samples show the contents of the four topic documents: about.dita, messages-install.dita, messages-run.dita, and messages-other.dita.

<!-- about.dita -->
<topic id="about">
  <title>About this guide</title>
  <shortdesc>Warnings or errors are displayed when ... <shortdesc>
</topic>
<!-- messages-install.dita -->
<dita>
  <topic id="INS001">
    <title>INS001: Installation failure</title>
    <!-- Explanation and recovery steps ... -->
  </topic>
  <!-- More topics that document installation messages ... -->
</dita>
<! messages-run.dita -->
<dita>
  <topic id="RUN001">
    <title>RUN001: Failed to initialize</title>
    <!-- Explanation and recovery steps ... -->
  </topic>
  <!-- Hundreds of message topics ... -->
  <topic id="RUN999">
    <title>RUN999: Out of memory</title>
    <!-- Explanation and recovery steps ... -->
  </topic>
</dita>
<!-- messages-other.dita -->
<topic id="othermsg">
  <title>Other messages</title>
  <shortdesc>You could also encounter ... </shortdesc>
  <topic id="OTHER001">
    <title>OTHER001: Analyzer is tired</title>
    <!-- Explanation and recovery steps ... -->
  </topic>
  <topic id="OTHER002">
    <title>OTHER002: Analyzer needs to be updated</title>
    <!-- Explanation and recovery steps ... -->
  </topic>
</topic>

When processed to HTML5, this map might result in four result documents: about.html, messages-install.html, messages-run.html, and messages-other.html.

Example 14. Splitting topics in one topic document

With hundreds of messages in messages-run.dita, it might be better in some situations to render one result document for each message topic in the document. This can be done by specifying chunk="split" on the topic reference to messages-run.dita:

<map>
  <title>Message guide</title>
  <topicref href="about.dita">
    <topicref href="messages-install.dita"/>
    <topicref href="messages-run.dita" chunk="split"/>
    <topicref href="messages-other.dita"/>
  </topicref>
</map>
Example 15. Equivalent content of source documents after evaluation

The result of evaluating @chunk in this case is equivalent to the following map. While messages-run.dita now is split into hundreds of topics, the other topics in the map are unaffected.

<map>
  <title>Message guide for WidgetAnalyzer</title>
  <topicref href="about.dita">
    <topicref href="messages-install.dita"/>
    <topicref href="RUN001.dita"/>
    <!-- Hundreds of topic references to message topics ... -->
    <topicref href="RUN999.dita"/>
    <topicref href="messages-other.dita"/>
  </topicref>
</map>
Note (non-normative):
Because the @chunk attribute does not cascade, even if the topic reference to messages-run.dita had child topic references, they would be unaffected by the chunk="split" operation in this example.
Splitting all topic documents in a map

This section is non-normative.

This example covers the scenario of splitting all the topic documents that are referenced in a DITA map.

Example 16. Root map with chunking specified

Specifying chunk="split" on the <map> element sets a default for the entire map. The following change to the DITA map results in every referenced DITA document being split into one document per topic. The only source document that is not affected by this splitting operation is about.dita, because it only contains only one topic.

<map chunk="split">
  <title>Message guide</title>
  <topicref href="about.dita">
    <topicref href="messages-install.dita"/>
    <topicref href="messages-run.dita"/>
    <topicref href="messages-other.dita"/>
  </topicref>
</map>
Example 17. Result of evaluating chunk="split"

The result of evaluating chunk="split" specified on the map element yields the following results:

  • about.dita is unchanged.
  • messages-install.dita is split into one document for each message.
  • messages-run.dita is split into one document for each message, exactly as in the previous example.
  • messages-other.dita contains a root topic and two child topics, so it results in three documents. The hierarchy of those documents is preserved in the map.
Example 18. Equivalent content of source documents after evaluation

The result of evaluating the @chunk attribute is the following map:

<map>
  <title>Message guide</title>
  <topicref href="about.dita">
    <topicref href="INS001.dita"/>
    <!-- More topic references to installation messages ... -->
    <topicref href="RUN001.dita"/>
    <!-- Hundreds of topic references to message topics ... -->
    <topicref href="RUN999.dita"/>
    <topicref href="othermsg.dita">
      <topicref href="OTHER001.dita"/>
      <topicref href="OTHER002.dita"/>
    </topicref>
  </topicref>
</map>

Example: How chunk="split" affects the map hierarchy

This section is non-normative.

Special attention is necessary when evaluating the map hierarchy that results from splitting documents that contain nested topics.

Figure 19. Source DITA map with chunking specified

Consider the following DITA map:

<map chunk="split">
  <title>Generation example</title>
  <topicref href="ancestor.dita">
    <topicref href="middle.dita">
      <topicref href="child.dita"/>
    </topicref>
  </topicref>
</map>

Here, the @chunk attribute instructs a processor to render every topic in each of the three documents as its own document, while preserving any hierarchy from those documents.

Figure 20. Source topic documents with nested or peer topics

Now consider the following three topic documents, each of which includes nested or peer topics:

<!-- ancestor.dita -->
<dita>
  <topic id="ancestor-first">
    <title>First major topic in ancestor composite document</title>
    <!-- ... Topic content ... -->
  </topic>
  <!-- More topics in ancestor composite document -->
  <topic id="ancestor-last">
    <title>Last major topic in ancestor composite document</title>
    <!-- ... Topic content ... -->
    <topic id="ancestor-last-child">
      <title>Child of last major topic in ancestor composite document</title>
      <!-- ... Topic content ... -->
    </topic>
  </topic>
</dita>
<!-- middle.dita -->
<topic id="middle-root">
  <title>Root topic in middle document</title>
  <body>
    <!-- ... -->
  </body>
  <topic id="middle-child">
    <title>Child of root topic in middle document</title>
    <!-- ... Body content, maybe more children topics ... -->
  </topic>
</topic>
<!-- child.dita -->
<topic id="child">
  <title>Small child topic</title>
  <!-- ... Topic content ... -->
</topic>
Figure 21. Evaluating chunk="split"

When chunk="split" is evaluated, both ancestor.dita and middle.dita are split and treated as multiple topic documents. child.dita is only a single topic and has nothing to split.

The following list addresses how the split operation effects the map hierarchy:

  • ancestor.dita has a root <dita> element, so it results in multiple peer topic references (or branches) in the map. Topic references that were nested within the original reference to ancestor.dita are now located within the reference to "ancestor-last" (the last topic child of the <dita> element).
  • middle.dita has nested topics, so it results in its own new hierarchy within the map. Content from the nested topic reference is now located within the reference to the root topic from middle.dita, but after any references to child topics.
Figure 22. Equivalent content of source documents after evaluation

The result of evaluating the @chunk attribute is equivalent to the following DITA map:

<map chunk="split">
  <title>Generation example</title>
  <topicref href="ancestor-first.dita"/>
  <!-- More topics in ancestor composite document -->
  <topicref href="ancestor-last.dita">
    <topicref href="ancestor-last-child.dita"/>
    <!-- middle.dita now located here, as final child of
         final topic child of <dita> in ancestor.dita -->
    <topicref href="middle-root.dita">
      <topicref href="middle-child.dita"/>
      <!-- child.dita now located here, as final topic of
           child root topic in middle.dita ancestor.dita -->
      <topicref href="child.dita"/>
    </topicref>
  </topicref>
</map>

Example: When @chunk is ignored

This section is non-normative.

The @chunk attribute is ignored in some cases, such as when chunk="combine" is already in effect or when chunk="split" is specified on a grouping element.

Figure 23. Ignoring @chunk when already combining topics

In the following code sample, evaluating chunk="combine" results in one rendered document for each map branch. Any additional @chunk values within those branches are ignored, including any @chunk values within any referenced maps.

<map>
  <title>Ignoring chunking when already combined</title>

  <topicref href="branchOne.dita" chunk="combine">
    <!-- @chunk ignored for branchOneChild.dita -->
    <topicref href="branchOneChild.dita" chunk="split"/>
  </topicref>

  <topicref href="branchTwo.dita" chunk="combine">
    <!-- Any @chunk within submap.ditamap is ignored -->
    <topicref href="submap.ditamap" format="ditamap"/>
  </topicref>
Figure 24. Ignoring @chunk on a grouping element

In the following code sample, chunk="split" is specified on two grouping elements.

<map>
  <title>Trying to "split" groups</title>
  <topicgroup chunk="split">
    <topicref href="ingroup1.dita"><!--...--></topicref>
    <topicref href="ingroup2.dita"><!--...--></topicref>
  </topicgroup>
  <topichead chunk="split">
    <topicmeta>
      <navtitle>Heading for a branch</navtitle>
    </topicmeta>
    <topicref href="inhead1.dita"><!--...--></topicref>
    <topicref href="inhead2.dita"><!--...--></topicref>
  </topichead>
</map>

The result of evaluating chunking is the following:

  • The @chunk attribute on the <topicgroup> element is ignored. The @chunk attribute does not cascade and there is no referenced topic, so it has no effect.
  • In some cases, an implementation might treat the <topichead> element as equivalent to a single title-only topic, while in other cases it might be ignored. In either case, the @chunk value has no effect. If the <topichead> is treated as a title-only topic, it cannot be split further. If it is ignored for the current processing context, it is no different than the <topicgroup> element.

Example: Using chunk="combine" when the root map specifies chunk="split"

This section is non-normative.

While @chunk attributes are ignored when chunk="combine" is already in effect, it is possible to use chunk="combine" when chunk="split" is in effect.

Figure 25. Source DITA map

Consider the following DITA map, where chunk="split" is specified on the root element. The effect of this operation is that all topic documents within the map structure are split by default. However, a map branch also specifies chunk="combine":

<map chunk="split">
  <title>Split most, but not one branch</title>
  <topicref href="splitme.dita">
    <!-- More topic references -->
  </topicref>
  <topicref href="exception.dita" chunk="combine">
    <!-- More topic references -->
  </topicref>
  <topicref href="splitmetoo.dita">
    <!-- More topic references -->
  </topicref>
</map>

Assume also that no other @chunk attributes are specified in the map.

Figure 26. Evaluation of @chunk attributes in the map

The following points are true when @chunk is evaluated:

  • The document splitme.dita is rendered as one result document for each topic.. The same is true for any other topic document within the map branch.
  • The second map branch, where the outermost <topicref> elements references exception.dita, is rendered as a single result document that combines all topic documents within the map branch.
  • The document splitmetoo.dita is rendered as one result document for each topic.. The same is true for any other topic document within the map branch.

Example: Managing links when chunking

This section is non-normative.

If a topic is referenced more than once and one of those instances involves chunking, links to that topic might be ambiguous. In most of such cases, using key references to keys that are defined directly on the chunked instance of the topic will give the correct result.
Figure 27. Source map and the topic documents that it references

Consider the following DITA map, which is used for all examples in this topic:

<map>
  <title>Map with chunks and key definitions</title>
  <!-- Key definitions -->
  <keydef href="splitThis.dita" keys="splitThisKey"/>
  <keydef href="splitThis.dita#splitThisChild" keys="splitThisChildKey"/>
  <!-- Navigational structure -->
  <topicref href="splitThis.dita" chunk="split" keys="explicitSplitKey"/>
  <topicref href="combineThis.dita" chunk="combine" keys="combineThisKey">
    <topicref href="combinedChild.dita" keys="combinedChildKey"/>
  </topicref>
</map>

The DITA map references the following topics:

<!-- splitThis.dita -->
<topic id="splitThisRoot">
  <title>Root topic</title>
  <!-- ... -->
  <topic id="splitThisChild">
    <title>Child topic</title>
    <!-- ... -->
  </topic>
</topic>
<!-- combineThis.dita -->
<topic id="combineThisRoot">
  <title>Root topic</title>
  <!-- ... -->
  <topic id="combineThisChild">
    <title>Child topic</title>
    <!-- ... -->
  </topic>
</topic>
<!-- combinedChild.dita -->
<topic id="combinedChildRoot">
  <title>Topic in map branch, will be combined with parent topicref</title>
  <!-- ... -->
</topic>
Figure 28. Scenario in which the topic documents are rendered only once

Assume that the above map is a root map or a submap that is referenced in a context that does not include any references to the above topic documents.

The topic documents that are referenced in the above map are rendered in the following ways:

  • splitThis.dita, which contains two topics, is rendered as two documents. For this example, assume the processor creates two documents with names that are based on the topic IDs: splitThisRoot.dita and splitThisChild.dita.
  • The map branch with combineThis.dita, which contains two topic references, is rendered as one document: combineThis.dita. The document contains the merged content of both combineThis.dita and combinedChild.dita.

Links are resolved in the following ways. Note that the document names are those listed in the above explanation of how the topic documents are rendered in this scenario.

  • All links that specify href="splitThis.dita", keyref="splitThisKey", or keyref="explicitSplitKey" resolve to splitThisRoot.dita, which is the only rendered instance of the topic.
  • All links that specify href="splitThis.dita#splitThisChild" or keyref="splitThisChildKey" resolve to splitThisChild.dita, which is the only rendered instance of the topic.
  • All links that specify href="combinedChild.dita" or keyref="combinedChildKey" resolve to that topic within combineThis.dita, which is the only rendered instance of the topic.
Figure 29. Scenario in which the topic documents are rendered more than once

Now assume that the above map is used as a submap in another context, where the root map also references the three topic documents. As a result, each of the three topic documents (splitThis.dita, combineThis.dita, and combinedChild.dita) are rendered more than once.

In this scenario, the topic documents are rendered in the following ways:

  • The original source document splitThis.dita is rendered twice. Based on the map above, assume the processor creates two documents with names that are based on the topic IDs, so that topic becomes splitThisRoot.dita and splitThisChild.dita. At the same time, splitThis.dita is rendered in another context as a single document, with a different name.
  • Based on the map above, the branch that starts with the original source document combineThis.dita is rendered as one document combined with the content of combinedChild.dita. At the same time, those two documents are rendered in another context as individual documents. For this example, assume a processor generates the combined document using the generated name combinThis-2.dita, while the documents combineThis.dita and combinedChild.dita retain their names in the other context.

In this scenario, the links to the topic documents are now problematic:

  • All links in this map that use the direct URI references href="splitThis.dita", href="splitThis.dita#splitThisChild", href="combineThis.dita", or href="combinedChild.dita" are ambiguous. They could resolve to either the chunked instance of the topic documents or to the individual topics in the other context. Implementations will have to guess which topic to target: the split or combined instances of the topic documents or the versions in the alternate context from the root map.
  • All links that specify keyref="splitThisKey" or keyref="splitThisChildKey" are also ambiguous. The key definitions are not associated explicitly with the chunked or not-chunked instance. If key scopes are used, applications might more reliably guess that the intended target is the split copy in this map, but this is not guaranteed.

All links that specify keyref="explicitSplitKey", keyref="combinedThisKey", or keyref="combinedChildKey" are unambiguous. These links can only resolve to the chunked instance of the topic documents, because the key definitions are defined directly within the chunked context.

There is no way to unambiguously link to the child document that will result from splitting splitThis.dita. This is because a <topicref> element that specifies @chunk can only associate a key definition with the first or root topic in the document. While other key definition elements can be used to associate keys with other topics in the same document, that can only be done outside of the navigation context that uses @chunk. As a result, a processor cannot guarantee whether the intended link target is the split topic from the chunked context or a use of the same topic in the second context.

It is possible for an implementation to define its own way to resolve this ambiguity. However, if a situation requires both multiple instances of split topics and unambiguous cross-implementation links to those split topics, alternate reuse mechanisms need to be considered.