articulation of chunk attribute for the DITA 1.1 specification

[Erik Hennum <ehennum@us.ibm.com>]

Hi, Esteemed Technical Committee:

In the DITA 1.0 language specification, the chunk attribute of the topicref element is underspecified.

http://docs.oasis-open.org/dita/v1.0/langspec/topicref-atts.html

The appended description attempts to nail down a precise definition of the chunk attribute for the DITA 1.1 specification.  While this description doesn't add anything to the document type or to the general processing expectations, it is more than mere clean up and should be reviewed.


Thanks,


Erik Hennum
ehennum@us.ibm.com


The chunk attribute controls the recognition of chunks of content within the output where output processing divides content across multiple files (such as hyperlinked HTML).

By default, chunking generates a single output file for each input unit. If the chunk attribute is set to the "content" token, the content for the referenced topic, any nested referenced topic, and any topics nested within those referenced topics is generated as a single output file. The root name for the output file is taken from the copyto attribute if set, the id attribute if copyto isn't set, and the referenced topic if neither the copyto or id attribute are set.

The following fragment would produce a single output file named parentchunk.html with both the parent and child1 content:

<topicref href=""parent.xml"" copyto="parentchunk" chunk="content">
    <topicref href=""child1.xml"/>

</topicref>

To produce a separate chunk within an explicit chunk, provide the chunk attribute on a nested topic reference. Use the "none" token to restore default chunking within an explicit chunk. The following example would generate the parent and child1 content in parentchunk.html, the child2 and grandchild2.1 content in child2chunk.html, the child3 content in child3.html, and the grandchild3.1 content in grandchild3.1.html:

<topicref href=""parent.xml"" chunk="content" copyto="parentchunk">
<topicref href=""child1.xml"/> <topicref href=""child2.xml"" chunk="content" copyto="child2chunk">
<topicref href=""grandchild2.1.xml"/> </topicref>
<topicref href=""child3.xml"" chunk="none">
<topicref href=""grandchild3.1.xml"/> </topicref>
</topicref>

To generate a separate output file from a topic that is nested within another topic within an input unit, refer to the nested topic with the href attribute and set the chunk attribute to the "content" token. The following example would generate the nested topic as nestedchunk.html:

<topicref href=""container.xml#nested"" copyto="nestedchunk" chunk="content"/>

Finally, if the chunk attribute is set to the "branch" token, the processing generates separate output units as usual. In addition, however, the processing can identify the topic as the root of a collection of topics that can be read independent from its context as the complete treatment of a subject for deployment frameworks that can manage topic collections.

For instance, a collection of topics might provide a learning module that can be administered by a Learning Management System. Similarly, a how to for setting up a product might be provided both as navigable HTML pages and as a single printable PDF:

<topichead navtitle="How to do lots of things">
<topicref href=""webserv.xml"" chunk="branch" navtitle="How to set up a web server">
<topicref href=""child1.xml"/> ...
</topicref>
<topicref href=""dbsecure.xml"" chunk="branch" navtitle="How to ensure database security">
<topicref href=""child2.xml"/> ...
</topicref>
...
</topicref>