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>