Chunking and Composite Topics

Hello All,

Kristen asked me to submit my recent work on the Chunking and Composite topic functions of DITA. With my colleagues Mark Poston and Rob Hanna we have been experimenting trying to use maps to leverage content that’s been either created in or converted to composite topics.

This email contains is an almost-copy-and-paste from our report to the client, but I’d also like to add my own (hastily put together) commentary.

<rant>

I find the chunking attribute syntax vastly overcomplicated. Instead of offering a good default that’s simply achieved, it offers something that’s expensive for vendors to implement and/or difficult to edit by hand. I have worked with the usual main players - FrameMaker, XMetaL, oXygen, Arbortext editor – and none offer any help or special functions around chunking. It’s only an advanced-user feature, and so it doesn’t really help move licenses for people getting started, and it requires quite a lot of UI to make usable. And the documentation in the spec is just a series of examples that don’t have full XML sets shown, just partial ones with prose description of what should happen on output.

Training on the functionality is a nightmare and I have actually had to look up the spec in a course when asked a question because the various permutations are so many and the tools do nothing to help.

I would suggest that there are two use cases being addressed with the chunking attribute, one is merging files together, the other is reusing them from files that are used together. This may be overloading the attribute.

The merging functionality makes sense, but the reuse/splitting options are rather opaque. I’d suggest by changing some of the default behaviours this could be made much easier.

My own take would be:

From a map, if you specify a child topic of a multi-topic file, then it’s safe to assume that that’s the topic you want, and not anything above (this is how most things in XML work, so it follows logically). So the default meanings could be:

<topicref href="" = “All topics in this file”

<topicref href="" = “All topics from topic id1a down”

<topicref href="" chunk="select-topic"> = “topic id1a only” (although it’s highly debatable whether this should be called using an attribute called “chunk” at all).

In a CCMS that uses IDs, there should be no change, you just split on the # like usual.

I’d suggest that simplifying the parameters passed to @chunk would enable more users to take advantage of it. I’m sure many are, but because of the complexity, lack of tool support, and resulting difficult to use for beginners, I believe many aren’t Googling the spec and learning how to use it.

</rant>

Reusing topics from a ditabase topic

If one uses chunking and conditions on the topicrefs then you can conditionally filter topics in and out and rearrange their hierarchy, even though they are stored in ditabase topics.

To reuse a topic from a ditabase topic:

1. Specify the topic id in the map and set the chunking attribute to “to-content select-topic” to insert a single topic or “to-content select-branch” or a topic and its descendants.

An example is supplied below of a DITAbase-based file being split up and reordered.

File noz-test.dita

<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">

<dita>

<title>Topic 1</title>

<body>

Topic 1.

Topic 1 has a cross reference to <xref href="" 1a</xref>.

Topic 1 has a cross reference to <xref href="" 1b</xref>.

</body>

<title>Topic 1a</title>

<body>

Topic 1a has a cross reference to <xref href="" 1</xref>.

Topic 1a has a cross reference to <xref href="" 1b</xref>.

</body>

<title>Topic 1b</title>

<body>

Topic 1b has a cross reference to <xref href="" 1</xref>.

Topic 1b has a cross reference to <xref href="" 1a</xref>.

</body>

</topic>

</dita>

Map

<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">

<map>

<title>DITA Topic Map</title>

</topicref>

</relcell>

</relcell>

</relrow>

</reltable>

</map>

Note:

· There appears to be a bug in the DITA OT that prevents rendering of topics with mixed topic types. All topics must be of the same type or else the transformation fails. The bug in the DITA OT is most likely in the Java extensions in the OT, not the XSLT. It should not be - if this is the only problem – particularly difficult to debug. Infineon must decide whether to:

o Fix the bug

o Make topics all the same type (most logically this would be all <topic>, within ditabase files. If this is done, as users and content are being migrated to the new, more modular way of working the topic types can and should be applied on individual topics.

o Not reuse below the topic level for now.

· The same limitations on xrefs apply with composite as with regular topics, and the same risks of broken links.

Limitations of composite topic type

· Simplified task is not included in the ditabase DTD. Ditabase DTD requires additional specialization to include simplified task.

· Composite files will only be able to be categorised as a whole in the taxonomy. As they are burst, the topics contained will have to be categorised after they are created.

· All IDs need to be unique across all topics – not just unique within a topic.

· Additional stylesheet work may be required to achieve publishing features such as mini-tables of contents (or forward organizers).

· Whole assemblies must be versioned with any change to a topic rather than simply versioning a single topic.

· Topic-type OT bug as described above.

</reportextract>

To you all for your attention.

</thanks>

B. Noz Urbina – Business Development Manager

blog http://lessworkmoreflow.blogspot.com ¦ twitter @nozurbina

e noz.urbina@mekon.com ¦ UK mob +44 (0)7739 522 002 ¦ ES mob +34 625 467 866 ¦ skype nozskype

dita message

Reusing topics from a ditabase topic

Limitations of composite topic type