The specification defines tokens for the chunk attribute that cover the most common chunking scenarios. These tokens can be used to override whatever default chunking behavior is set by a processor. Chunking is necessarily format specific, with chunked output required for some and not supported for other rendered formats. Chunking is also implementation specific with some implementations supporting some, but not all, chunking methods, or adding new methods to the standard ones 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.
- Selecting topics
- When addressing a document that contains multiple topics, these values determine
which topics are selected. These values are ignored when the element on which they
are specified does not reference a topic. The defined values are:
- select-topic: Selects an individual topic without any ancestors, descendents, or peers from within the same document.
- select-document: Selects all topics in the target document.
- select-branch: Selects the target topic together with its descendent topics.
- Policies for splitting or combining documents
- The chunking policy tokens determine how source topics are chunked to produce
different output chunks, for output formats where that makes sense. When specified
on a map element, the policy becomes the default policy
for all topic references. When specified on a topic reference, the policy applies
only to that topicref and not to any descendant
- by-topic: A separate output chunk is produced for each of the selected topics. In particular, topics that are part of multi-topic documents are processed as though they are the root topics within a separate XML document.
- by-document: A single output chunk is produced for the referenced topic or topics, as though the selected topics were all children of the same document.
- Rendering the selection
- The following tokens affect how the chunk values impact rendering of the map or
- to-content: The selection should be rendered as a
new chunk of content.
- When specified on a topicref, this means that the topics selected by this topicref and its children will be rendered as a single chunk of content.
- When specified on the map element, this indicates that the contents of all topics referenced by the map are to be rendered as a single document.
- When specified on a topicref that contains a title but no target, this indicates that processors MUST generate a title-only topic in the rendered result, along with any topics referenced by child topicref elements of this topicref. The rendition address of the generated topic is determined as defined for the copy-to attribute. If the copy-to attribute is not specified and the topicref has no id attribute, the address of the generated topic is not required to be predictable or consistent across rendition instances.
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.
- to-navigation (DEPRECATED): The "to-navigation" token is deprecated in DITA 1.3. In earlier releases, the "to-navigation" token indicates that a new chunk of navigation should be used to render the current selection (such as an individual Table of Contents or related links). When specified on the map element, this token indicates that the map should be presented as a single navigation chunk. If a cross reference is made to a topicref that has a title but no target, and the chunk value of that topicref is set to "to-navigation", the resulting cross reference is treated as a reference to the rendered navigation document (such as an entry in the table of contents).
- to-content: The selection should be rendered as a new chunk of content.
Some tokens or combinations of tokens might not be appropriate for all output types. When unsupported or conflicting tokens are encountered during output processing, processors SHOULD produce warning or error messages. Recovery from such conflicts or other errors is implementation dependent.
There is no default value for the chunk attribute on most elements 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 can 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 specified or defaulted, chunking behavior is implementation dependent. When variations of this sort are not desired, a default for a specific map can be established by including a chunk attribute value on the map element.
When chunk processing results in new documents, the resource name or identifier for the new document (if relevant) is determined as follows:
- If an entire map is used to generate a single chunk (by placing to-content on the map element), the resource name SHOULD be taken from the resource name of the map.
- If the copy-to attribute is specified, the resource name MUST taken from the copy-to attribute.
- If the copy-to attribute is not specified and one or more keys are specified on the topicref, the resource name SHOULD be constructed using one of the keys.
- If copy-to and keys are not specified and the by-topic policy is in effect, the resource name SHOULD be taken from the id attribute of the topic.
- If copy-to and keys are not specified and the by-document policy is in effect, the resource name SHOULD be taken from the resource name of the referenced document.
When following these steps results in resource name clashes, processors MAY recover by generating alternate resource identifiers. For example, when two chunked topics use the same id attribute, a processor could recover by combining the original resource name with the id value instead of using only the id value.
Implementation-specific tokens and future considerations
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 token or method name.
For example: “acme:level2” could be a token for the Acme DITA Toolkit that requests the “level2” chunking method.