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 multi-topic documents into component topics or combine multiple topics into a single document as part of output processing.
Here are some examples of potential uses of the chunk attribute:
A content provider creates a set of topics as a single document. Another user wants to incorporate only one of the nested topics from the document. The new user can reference the nested topic from a DITA map, using the chunk attribute to specify that the topic should be produced in its own document.
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.
When a set of topics is processed for output using a map, the map author may use the chunk attribute to override whatever default chunking behavior is set by the processor. The chunk attribute allows the map author to request that multi-topic documents be be broken into multiple documents, and that multiple individual topics be combined into a single document.
Chunking is necessarily output processor 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. Tokens are defined in three categories: for selecting topics, for setting chunking policies, and for defining how the chunk values impact rendering. It is an error to use two tokens from the same category on a single topicref element.
These values describe what portion of a target document is referenced. Such tokens are only useful when addressing a document that is made up of multiple topics. These values are ignored when the element on which they are specified does not reference a topic. Recognized values include:
Policies for splitting or combining documents
Two tokens are defined for setting chunking policies. Each token applies only to the current topicref or topicref specialization, except when used on the map element, in which case the value establishes a policy for the entire map.
The following tokens affect how the chunk values impact rendering of the map or topics.
For cross references to topicref elements, if the value of the chunk attribute is "to-content" or is unspecified, the cross reference is treated as a reference to the target topic. If the reference is to a topicref with no target, it is treated as a reference to the generated title-only topic.
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 or error messages should 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 cascade from container elements, meaning that the chunk value on one topicref is not passed to its children. A default by-xxx policy for an entire map may be established by setting the chunk attribute on the map element, which will apply to any topicref that does not specify its own by-xxx policy.
When no chunk attribute values are given, chunking behavior is implementation dependent. When variations of this sort are not desired, a default for a specific map may be established by including a chunk attribute value on the map element.
When creating new documents via chunk processing, the storage object name or identifier (if relevant) is determined as follows:
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 may actually be ".html", but this is not required.
The examples below assume the existence of the following files:
<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>
<map chunk="to-content"> <topicref href="parent1.dita"> <topicref href="child1.dita"/> <topicref href="child2.dita"/> </topicref> </map>
<map chunk="by-topic"> <topicref href="parent1.dita"> <topicref href="nested1.dita"/> </topicref> </map>
<map> <topicref href="parent1.dita"> <topicref href="child1.dita" chunk="to-content"> <topicref href="grandchild1.dita"/> <topicref href="grandchild2.dita"/> </topicref> </topicref> </map>
<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>
<map chunk="by-document"> <topicref href="parent1.dita" chunk="to-content"> <topicref href="ditabase.dita#Y1" chunk="select-topic"/> </topicref> </map>
<map chunk="by-document"> <topicref href="parent1.dita" chunk="to-content"> <topicref href="ditabase.dita#Y1" chunk="select-branch"/> </topicref> </map>
<map chunk="by-topic"> <topicref href="parent1.dita" chunk="to-content"> <topicref href="ditabase.dita#Y1" chunk="select-document"/> </topicref> </map>
<map chunk="by-document"> <topicref href="parent1.dita" chunk="to-content" copy-to="parentchunk.dita"> <topicref href="nested1.dita" chunk="select-branch"/> </topicref> </map>
<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>
<map> <topicref href="nested1.dita#N1" copy-to="nestedchunk.dita" chunk="to-content select-topic"/> </map>
<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>
Additional chunk tokens may be added to the DITA Standard in the future. In addition, implementers may define their own custom, implementation-specific tokens. 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.