@chunk
attributeThe specification defines tokens for the @chunk
attribute that cover
the most common chunking scenarios. These tokens may 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.
<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 <topicref>
elements.<topicref>
, this means
that the topics selected by this <topicref>
and
its children will be rendered as a single chunk of content.<map>
element, this
indicates that the contents of all topics referenced by the map are to
be rendered as a single document.<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.
<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).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 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 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:
<map>
element), the resource name SHOULD be taken from the
resource name of the map.@copy-to
attribute is specified, the resource name MUST taken from the
@copy-to
attribute.@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.@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.@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.
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.
Return to main page.
dita-v1.3-csd01-part1-base Standards Track Work Product | Copyright © OASIS Open 2015. All Rights Reserved. | 30 June 2015 |