Search results

DITA: Combining topics

You can combine topics into longer articles using the chunk attribute on your map. This issue usually crops up if you're using the specialized topic types (task, concept) and you're trying to combine information.

As I recommended in DITA: Specializations (task, concept, reference)?, author in the base topic type. You won't find yourself doing acrobatics to combine topics. However, you may want to combine topics in order to create nested subheadings.

Combining topics with the chunk attribute

The chunk="to-content" attribute allows you to merge child topics into a parent topic in your navigation. You add the chunk attribute on a parent topicref. 

  <topicref href="parent.dita" chunk="to-content">
  <topicref href="child1.dita" toc="no"/>
  <topicref href="child2.dita" toc="no"/>
  </topicref>

If you want the child topics to actually appear in the table of contents, use the "yes" value.

Although the chunk attribute works easily enough in the TOC area, it's problematic with linking. Chunking creates issues with relationship tables. (See DITA: Limitations with the chunk=”to-content” attribute in relationship tables.)

Combining topics by nesting elements

A better way to combine topics is by nesting elements. When you nest elements, you add multiple taskbody or conbody elements inside each other. Here's an example of how nest task elements.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task id="task_0">
    <title>Fixing a flat tire</title>
    <shortdesc></shortdesc>
    <taskbody>
        <context>
            <p>This is an overview about the task of fixing a flat tire...</p>
        </context>

    </taskbody>

    <task id="task_1">
        <title>Remove the tire</title>
        <shortdesc/>
        <taskbody>
            <context>
                <p>Context for the current task</p>
            </context>
            <steps>
                <step>
                    <cmd>Task step.</cmd>
                </step>
            </steps>
        </taskbody>
    </task>

        <task id="task_2">
            <title>Inspect the tire</title>
            <shortdesc/>
            <taskbody>
                <context>
                    <p>Context for the current task</p>
                </context>
                <steps>
                    <step>
                        <cmd>Task step.</cmd>
                    </step>
                </steps>
            </taskbody>
        </task>

            <task id="task_3">
                <title>Insert a new tube</title>
                <shortdesc/>
                <taskbody>
                    <context>
                        <p>Context for the current task</p>
                    </context>
                    <steps>
                        <step>
                            <cmd>Task step.</cmd>
                        </step>
                    </steps>
                </taskbody>

            </task>

                <task id="task_4">
                    <title>Reinstall the tire</title>
                    <shortdesc/>
                    <taskbody>
                        <context>
                            <p>Context for the current task</p>
                        </context>
                        <steps>
                            <step>
                                <cmd>Task step.</cmd>
                            </step>
                        </steps>
                    </taskbody>
                </task>

</task>

With nesting concepts, here's what that looks like

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="concept_1">
 <title>License overview</title>
 <conbody>
  <p>Here's some overall information about your license....</p>
 </conbody>

 <concept id="concept_2">
  <title>Getting your license</title>
  <conbody>
   <p>Inforamtion about activating your license...</p>
  </conbody>

 <concept id="concept_3">
  <title>Registering your license</title>
  <conbody>
   <p>Information about registering your license...</p>
  </conbody>
</concept>

</concept>

Basically, just bookend the individual task or concept elements inside one task or concept element that functions as a container.

Using an outputclass for a third-level section

You can also "cheat" to combine topics against the design of the DITA structure by crafting an outputclass attribute to look like a third-level heading: like this: 

         <p outputclass="level3">Sample heading</p>

Then add p.level3 class to the webhelp stylesheet. Assuming your OxygenXML install directory begins in your /Applications folder, the path would be as follows:

/Applications/oxygenAuthor/frameworks/dita/DITA-OT/plugins/com.oxygenxml.webhelp/oxygen-webhelp/resources

Open the webhelp_topic.css file, scroll down to the bottom, and add something like this for your style: 

.level3 {
  color: #444;
  font-size: 16px;
  font-style: italic;
}

This is more of a workaround hack than any good technique. Sometimes you just need a third-level heading, though, and this works.

About Tom Johnson

Tom Johnson

I'm a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out my API documentation if you're looking for more info about that. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.

© 2023 Tom Johnson