Thanks to Jeff Ogden for the write-up:
Chapter 3, DITA markup : DITA maps : Common
DITA map attributes and metadata : Navigation, media, and chunking attributes
chunk
When a set of topics is transformed using
a map, multi-topic files can be broken into smaller files, and multiple
individual topics can be combined into a single larger file, using the
chunk attribute. There is no default value for the chunk attribute, but
a default for an entire map may be established by setting the chunk attribute
on the map element or a specialization. For a detailed description of the
chunk attribute and its usage see the section on Chunking in Chapter 4.
copy-to
When a set of topics is transformed using
a map, duplicate topic versions can be created using the copy-to attribute.
The copied topic will have a new file name or location as provided in the
copy-to attribute, and the map can override the default title and shortdesc
for this particular copy by providing values for them in the map. . For
information on how the copyto attribute can be used with the chunk attribute
see the section on Chunking in Chapter 4.
Chapter 3, DITA markup : DITA maps : Inheritance
of attributes and metadata : Attributes
Before: …, chunk, format, scope, type
After:
…, format, scope, type
Add: While the chunk attribute no longer
inherits a value from containers (new with DITA 1.1), specifying a value
for the chunk attribute on the map or map specialization element establishes
a default value for chunking that applies to the entire map unless overridden
by more specific chunk attribute settings elsewhere within the document.
Chapter 4, DITA behaviors : Chunking
Chunking
Content may be chunked (divided or merged
into new output documents) in different ways for the purposes of authoring,
for delivering content, and for navigation. For example, something best
authored as a set of separate topics may need to be delivered as a single
Web page. A map author can use the chunk attribute to split up single documents
into component topics or combine multiple topics into a single document
as part of output processing.
Examples of use
Here are some examples of potential uses
of the chunk attribute:
Reuse of a nested topic – A content
provider creates a set of topics as a single module. A reuser wants to
incorporate only one of the nested topics from the module. The reuse can
reference the nested topic from a DITA map, using the chunk attribute to
specify that the topic should be produced in its own file.
Identification of a set of topics as a
unit – A curriculum developer wants to compose a lesson for a SCORM
LMS (Learning Management System) from a set of topics without constraining
reuse of those topics. The LMS can save and restore the learner’s progress
through the lesson if the lesson is identified as a referenceable unit.
The curriculum developer defines the collection of topics with a DITA map,
using the chunk attribute to identify the learning module as a unit before
generating the SCORM manifest.
Use of the chunk attribute
When a set of topics is transformed for output
using a map, the map author may use the chunk attribute to override the
implementation specific default behavior. The chunk attribute allows the
map author to request that multi-topic files be broken into smaller files,
and that multiple individual topics be combined into a larger files. Chunking
is necessarily output transformation specific with chunked output required
for some and not supported for other types of output. Chunking is
also implementation specific with some implementations supporting some,
but not all, chunking methods, or adding new implementation specific chunking
methods to the standard methods described in this specification.
The value of the chunk attribute consists
of one or more space delimited tokens:
by–topic – When the chunk attribute
value includes the “by–topic” token, a chunking policy is established
for the current topicref element where a separate output document is produced
for each source topic in the referenced document. The policy only applies
for a chunk action of the current element (for example, to-content), except
when it is set on the map or map specialization element, when the “by-topic”
policy is established for the entire map.
by–document – When the chunk attribute
value includes the “by–document” token, a chunking policy is established
for the current topicref element where a single output document is produced
for the referenced document. The policy only applies for a chunk action
of the current element (for example, to-content), except when it is set
on the map or map specialization element, when the “by-document” policy
is established for the entire map.
select–topic – When the chunk attribute
value includes the “select–topic” token, an individual topic, without
any other topics (ancestors, descendents, or peers) from within the same
document, is selected.
select–document – When the chunk
attribute value includes the “select–document” token, the content for
the referenced topic, as well as any other topics (ancestors, descendents,
or peers) contained within the same document are selected.
select–branch – When the chunk attribute
value includes the “select–branch” token, an individual topic as well
as any nested topics it contains are selected.
to–content – When the chunk attribute
value includes the “to–content” token, processing generates a new chunk
of content.
to–navigation – When the chunk attribute
value includes the “to–navigation” token, processing generates new chunk
of navigation (toc, related-links).
Note that the set of select–xxxxx token
values are only useful when addressing a topic in a document that contains
multiple topics.
Some tokens or combinations of tokens may
not be appropriate for all output types. When unsupported or conflicting
tokens are encountered during output processing, warning and error messages
may be produced. Recovery from such conflicts or other errors is
implementation dependent.
There is no default value for the chunk attribute
and the chunk attribute does not inherit values from container elements.
A default for an entire map may be established by setting the chunk attribute
on the map or map specialization element.
When no chunk attribute values are given,
chunking behavior is implementation dependent and may vary for different
implementations. When variations of this sort are not desired, a
default for the entire map may be established by including a chunk attribute
value on the map or map specialization element.
The root name for an output file is taken
from the copyto attribute if set, otherwise the root name is taken from
the id attribute if the by-topic policy is in effect and from the name
of the referenced document if the by-document policy is in effect.
Examples
Given several single topic files, parent1.dita,
parent2.dita, …, child1.dita, child2.dita, …, grandchild1.dita, grandchild2.dita
containing topics with ids P1, P2, …, C1, C2, …, GC1, GC2, …., several
nested topic files, nested1.dita, nested2.dita, …, each containing two
topics, parent topics with ids N1, N2, … and child topics with ids N1a,
N2a, … nested within the parent, and ditabase.dita with the following
contents:
<dita>
<topic id="X"/>
<topic id="Y">
<topic id="Y1">
<topic
id="Y1a"/>
</topic>
<topic id="Y2"/>
</topic>
<topic id="Z">
<topic id="Z1"/>
</topic>
</dita>
map1.ditamap:
<map chunk=”by-document”>
<topicref href="parent1.dita"
chunk="to-content">
<topicref href="ditabase.dita#Y1"
chunk="select-topic"/>
</topicref>
</map>
Produces a single output file, parent1.xxxx
containing topic P1 with topic Y1, but not topic Y1a nested in it.
map2.ditamap:
<map chunk=”by-document”>
<topicref href="parent1.dita"
chunk="to-content">
<topicref href="ditabase.dita#Y1”
chunk=”select-branch”/>
</topicref>
</map>
Produces a single output file, parent1.xxxx
containing topic P1, topic Y1 nested within topic P1, and topic Y1a nested
within Y1.
map3.ditamap:
<map chunk=”by-topic”>
<topicref href="parent1.dita"
chunk="to-content">
<topicref href="ditabase.dita#Y1”
chunk=”select-document”/>
</topicref>
</map>
Produces a single output file, P1.xxxx, containing
topic P1 and topics X, Y, and Z together with their children nested within
topic P1.
map4.ditamap:
<map chunk=”by-document”>
<topicref href="parent1.dita"
copyto="parentchunk">
<topicref href="nested1.dita"
chunk=”select-branch”/>
</topicref>
</map>
Produces a single output file named parentchunk.xxxx
containing topic P1 with topic N1 nested within P1 and topic N1a nested
within N1.
map5.ditamap:
<map chunk=”by-document”>
<topicref href="parent1.dita"
chunk="to-content"
copyto="parentchunk">
<topicref href="child1.dita"
chunk=”select-branch”/>
<topicref href="child2.dita"
chunk="to-content
select-branch"
copyto="child2chunk">
<topicref
href="grandchild2.dita"/>
</topicref>
<topicref href="child3.dita">
<topicref
href="grandchild3.dita"
chunk=”select-branch”/>
</topicref>
</topicref>
</map>
Produces two output files: the P1, C1, C3,
and GC3 topics in parentchunk.xxxx, and the C2 and GC2 topics in child2chunk.xxx.
map6.ditamap:
<map>
<topicref href="nested1.dita#N1"
copyto="nestedchunk"
chunk="to-content
select-topic"/>
</map>
Produces a single output file, nestedchunk.xxxx,
which contains topic N1 with no topics nested within.
map7.ditamap:
<map>
<topichead navtitle="How
to do lots of things"
chunk=”to-navigation”>
<topicref
href="parent1.dita"
navtitle="How to set up a web server">
<topicref href="child1.dita"
chunk=”select-branch”/>
...
</topicref>
<topicref
href="parent2.dita"
navtitle="How to ensure database security">
<topicref href="child2.dita"
chunk=”select-branch”/>
...
</topicref>
...
</topicref>
</map>
Produces two navigation chunks, one for P1,
C1, … and a second for P2, C2, ….
The above example identifies a “how to”
for setting up a product as a single unit. The “how to” might be provided
both as navigable HTML pages and as a printable PDF attached to the root
HTML page.
Implementation specific tokens and future
considerations
Additional chunk tokens may be added to the
DITA Standard in the future. Additional implementation specific tokens
may be defined as well. To avoid name conflicts between implementations
or with future additions to the standard, implementation specific tokens
should consist of a prefix that gives the name or an abbreviation for the
implementation followed by a colon followed by the chunking method name.
For example: “acme:level2” could be a token for the Acme
DITA Toolkit that requests the “level2” chunking method.
For use in the %topicref-atts; and %topicref-atts-no-toc;
descriptions in Chapter 23 of the DITA 1.1 Language Reference Specification:
| Name
| Description
| Data Type
| Default Value
| Required?
|
| chunk
| When a set of topics is transformed using
a map, the chunk attribute allows multi-topic files to be broken into smaller
files, and multiple individual topics to be combined into larger
combined files.
For a detailed description of the chunk attribute
and its usage see the section on Chunking in Chapter 4 of the DITA 1.1
Architectural Specification.
| CDATA
| #IMPLIED
| No |
Michael Priestley
IBM DITA Architect and Classification Schema PDT Lead
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25