DITA 1.3 overview

Jake Campbell / Opinion3 Comments

Robert Anderson, one of the DITA architects, compared the transition from DITA 1.1 to DITA 1.2 to the difference between having a couple of drinks with friends and a huge party. The DITA 1.2 specification introduced broad changes in the form of new base elements, new architectural structures, and new specializations.

DITA 1.3 isn’t the rowdy gathering that DITA 1.2 was—it’s more a group of friends going out to the new pub downtown while being sure to get some designated drivers. This article describes the most important additions to DITA 1.3.

Scoped keys

In DITA 1.2, keys were always global. That is, a key could only use one value in a ditamap. If you needed a key to use two different values in different parts of a single ditamap file, you were out of luck.

DITA 1.3 addresses this problem with the @keyscope attribute. The @keyscope attribute lets you constrain the value of a key to a specific part of the ditamap. In effect, you create a local key instead of a global key. This is useful for omnibus publications or for publications that are authored by multiple teams. For example, consider a widget repair manual that describes two different products. It needs to reference the prodinfo key, but with two different values. The @keyscope attribute supports this requirement.

<map>

<title>Widget Repair Manual</title>
<topichead navtitle=”Widget A” keyscope=”Widget_A”>
<keydef keys=”prodinfo” href=”prodinfo_a.dita”/>
<topicref href=”maintenance_a.dita”/>
</topichead>
<topichead navtitle=”Widget B” keyscope=”Widget_B”>
<keydef keys=”prodinfo” href=”prodinfo_b.dita”/>
<topicref href=”maintenance_b.dita”/>
</topichead>


</map>

Before DITA 1.3, this scenario required two different keys or separate publications for each widget. To reference a key within a specific scope, add a scope before the key name. For example, to explicitly reference Widget B’s product information, use Widget_B.prodinfo as the key value. If no scope is declared, the scope of the current topic is used instead.

Cross-deliverable linking

DITA 1.3 also provides support for cross-deliverable linking through scoped keys. First, you create a mapref, set the @scope attribute to peer, and then define a keyscope.

<map>

<title>Widget User Guide</title>
<mapref href=”../Repair_Manual/Repair_Manual.ditamap” scope=”peer” keyscope=”Repair_Manual”/>


</map>

Then you can use keys contained in the referenced map within the publication. In this example, topics within the Widget User Guide can use keys that are defined in Repair_Manual.ditamap. For example, to reference a task detailing the repair of a feature, an author could do the following:

<p>If replacing the module did not work, see <xref keyref=”Repair_Manual.wiring_harness”/> in <conkeyref=”Repair_Manual.title”/> for detailed instructions on how to repair the wiring harness.</p>

Branch filtering

In DITA 1.2, ditavals are global and applied when running a transform. In DITA 1.3, the <ditavalref> element allows you to specify ditavals at the map or topicref level and then cascade the filtering effects through the map. Consider a software documentation guide.

<map>

<title>App User Manual</title>
<topicref href=”prodinfo.dita>

          <ditavalref href=”user.ditaval”/>

</topicref>
<topicref href=”functions.dita”>

<ditavalref href=”mac.ditaval”/>
<ditavalref href=”windows.ditaval”/>
<ditavalref href=”linux.ditaval”/>

</topicref>


</map>

When output is generated from this map, prodinfo.dita is published using the settings in user.ditaval. In addition, functions.dita is published three times, once for each of the three ditaval files specified.

Troubleshooting

The new troubleshooting topic type is a specialization of the task topic type intended for troubleshooting steps, and consists of <condition>, <cause>, and <remedy> elements. You can use multiple cause/remedy pairs to provide a series of corrective actions for conditions that can have multiple causes.

The optional <tasktroubleshooting> and <steptroubleshooting> elements and trouble admonition type are used to provide quick, embedded troubleshooting within a topic. The DITA 1.3 specification recommends that these elements contain a condition, cause, and remedy.

The big picture

There are a lot of new toys to work with in DITA 1.3, and we haven’t even looked at some of the smaller additions, like new attributes for tables and organizational elements within topics. There are a lot of necessities to consider, but will your vendors support them, and how soon?

How could some of these new features be used to your advantage? Have you already implemented similar functionality yourself?

About the Author

Jake Campbell

Technical Consultant. Five years of experience in game industry QA, with a background in education and editing. DITA-OT plugin nerd, scholar of arcane InDesign rituals. Interested in games, game design, eating everything, and wiener dogs.

3 Comments on “DITA 1.3 overview”

  1. Hi, nice summary of some of the new features. I just wanted to note a couple of syntax tweaks that are only really relevant if people start trying to play with the actual markup. First – the keyscope syntax is actually scopeName.keyValue rather than keyValue.scopeName. Second, in the branch filtering markup, the reference to “user.ditaval” should be nested inside “prodinfo.dita” rather than directly after it (I’m pretty sure that’s already what you intended based on the indenting).

    Cheers – and looking forward to hearing how people hope to make use of these!
    Robert

  2. Pingback: Draft DITA 1.3 Specification Now Publicly Available | DITA Writer

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.