June 2012
By Tom Aldous

Tom Aldous, Director - TechCom Business Development and Evangelism at Adobe Systems, Inc., is responisble for worldwide Adobe TechCom business development and product evangelism. Prior to this, Tom was Managing Partner of Adobe Business Partner Integrated Technologies, Inc. for over 20 years.

What can DITA 1.2 do for me?

Darwin Information Typing Architecture (DITA) has proven to be an excellent choice for maximizing content reuse. However, if you use older versions of DITA you may be wondering why you should use DITA 1.2 (the latest version as of 2011). If you are not using DITA, you may be curious whether the latest DITA 1.2 features are useful enough for you to try DITA.

DITA – a short introduction

Historically, technical communicators often created long documents in the form of books. For example, a software package normally included multiple books such as a user guide and a reference manual. These documents overlapped in significant amounts of information, and this duplicate information resulted in higher costs since it had to be written, edited, translated, and maintained more than once.

In contrast to long books, DITA breaks content down into small pieces, called topics. A document is made of a map that points to a combination of topics, and these topics can be reused by multiple documents. For example, the maps for a user guide and a reference manual may point to many of the same topics, in addition to topics that are unique to each document. A topic that is reused by multiple documents saves money since it only has to be created once, which is something that appeals to any manager trying to lower costs.

DITA has these basic types of topics:

  • Task: topics describing how to do something step-by-step
  • Concept: topics describing definitions, rules, and guidelines.
  • Reference: topics describing command syntax and other reference material that is usually detailed and factual
  • Glossary entry

Typically, each topic covers a specific subject with one purpose. These basic topic types can be specialized into new topic types that fit your specific company or industry.

DITA map and topic documents follow an XML format. There are many tools that can edit XML. Once the document maps and topics are created, multiple deliverables, such as PDF, print, online Help, and HTML can be published.

DITA was created by IBM but is now an open-source standard, approved and supported by OASIS, which publishes a free toolkit for open-source processing support.

General task module

Before DITA 1.2 a common complaint was that DITA could not handle the complexity of some tasks.

DITA 1.2 broadens the general task model to allow:

  • multiple sets of steps
  • warning notices at the start of a step
  • extra freedom in the order of blocks
  • a section for generic information

Users creating a new DTD/Schema may use the original model with the same constraint, a new constraint, or no constraint at all (constraints are discussed later in this article).

Keys and keyref attributes used with <keydef> element

The keys and keyref attributes allow you to set up a redirection scheme. You do this by leveraging the existing map architecture. The idea is that you associate a target with a key, then create links to the target by using the key. This allows you to increase the reusability of your content.

The keys and keyref attributes refer to <keydef> elements. <keydef> is a convenience element – a specialized <topicref> that sets the default value of the @processing-role attribute to resource-only. <keydef> binds a key name to a specified resource, such as a website address. For example, you can define a <term> or <xref> that readers can click on for more information.

In example below, an “LCD” key is defined that links to Wikipedia. The target href and key “LCD” are defined in a <keydef> in a map:

<map>

<keydef

keys="lcd"

href="http://en.wikipedia.org/wiki/LCD"

format="html"

scope="external"

/>

...

</map>


The key can be used to create a link out of the “LCD” term. It also may be substituted for an href:

Your next TV should be an <term keyref="lcd">LCD</term>.

For more information, see <xref keyref="lcd">Wikipedia</xref>.

The output looks like this:

Your next TV should be an LCD.

For more information, see Wikipedia.

keyref attribute accesses text from the map

DITA 1.2 allows the keyref attribute on <keyword> to get text from the map. In this example, the <keydef> is defined in file “lcd-brand-keys.dita”:

<map title="LCD TV help">

<keydef keys="lcd-brand" href=">

<topicmeta>

<keywords>

<keyword>Oak Mountain Big Screen TV</keyword>

</keywords > </topicmeta>

</keydef>

...

</map>


Now <keyref> can reference the brand name:

<task ...>

...

We hope you enjoy your <keyword keyref="lcd-brand" /> TV.

The output looks like this:

We hope you enjoy your Oak Mountain Big Screen TV

Conref attribute extensions

Conref is a way to include one topic in another. More generally, it pulls the referenced content into the location of the referencing element. DITA 1.2 added useful enhancements that allow you to reference just part of a topic, push updated information to topics, or preserve conref without resolving.

Conref include/pull range

Assume you want to include just three steps from another task, (this is called “pulling”). Before DITA 1.2, you needed three separate elements containing conref. Now you only need one. You do this by specifying a range using the new conrefend attribute along with the old conref attribute.

In this example, file “source-file.dita” includes the topic “source-topic” which contains list items:

<topic id=”source-topic”>
...
    <ol>
    <li id=”first-li”>First</li>
    <li id=”second-li”>Second</li>
    <li id=”third-li”>Third</li>
    <li id=”fourth-li”>Fourth</li> <li id=”fifth-li”>Fifth</li>
...

Below is a referencing topic that pulls the second, third and fourth list item from the source file by using conref and conrefend:

<topic id=”referencing-topic”>
...
    <ol>
    <li>This list item is before the included list items</li>
    <li
conref=”source-file.dita#source-topic/second-li”
conrefend=”source-file.dita#source-topic/fourth-li”
    />
    <li>This list item is after the included list items</li>
...

The referencing-topic output looks like this:

This list item is before the included list items
Second
Third
Fourth
This list item is after the included list items

Conref push

When one topic inserts information into another topic, it is called “pushing”. Pushing is handy when you want to modify information (such as adding new steps) in an existing topic without actually modifying the existing topic file. Up until now all you could do was modify a topic to “pull” information into itself, as in the previous conref range example.

You specify how the information is pushed into the existing topic by choosing one of three methods:

  • insert the information just before an element
  • insert the information just after an element
  • replace the information contained in an element
  • You specify the element affected by specifying its ID.

 

Conref push replace

This allows you to replace the contents of an element. Just for fun, our example will use the specialized “task” topic rather than a generic topic. As shown below, file “source-file.dita” contains topic “source-task”, which contains task steps. As you can see, the third step needs to be replaced:

<task id=”source-task”>
...
    <steps>
    <step id=”first-step”><cmd>First command</cmd></li>
    <step id=”second-step”><cmd>Second command</cmd></li>
    <step id=”third-step”><cmd>This is not correct</cmd></li>
    <step id=”fourth-step”><cmd>Fourth command</cmd></li> <step id=”fifth-step”><cmd>Fifth command</cmd></li>
...

Here is a referencing topic that replaces the content of the third step:

<task id=”pushing-task”>
...
    <steps>
    <step
conaction=”pushreplace”>
conref=”source-task.dita#source-task/third-step”
    >
    <cmd>This is the correct third command</cmd>
    </step>
    ...

The pushing-task output looks like this:

First command
Second command
This is the correct third command
Fourth command
Fifth command

Conref push after

This example inserts new content after an element instead of replacing content. Note how step 3 is missing:

<task id=”source-task”>
...
    <steps>
    <step id=”first-step”><cmd>First command</cmd></li>
    <step id=”second-step”><cmd>Second command</cmd></li>
    <!-- Notice how step 3 is missing -->
    <step id=”fourth-step”><cmd>Fourth command</cmd></li> ...

First, a <step> must specify the conref and specify conaction=”mark” (this prevents an invalid structure from being created). Next, a step specifies -conaction=”pushafter” and the missing command:

<task id=”pushing-task”>
...
    <steps>
    <step conaction=”mark”>
conref=”source-task.dita#source-task/second-step”
    />
    <step conaction=”pushafter”>
    <cmd>Third command</cmd>
    </step>
    ...

The pushing-task output looks like this:

First command
Second command
Third command
Fourth command

Conref push before

To push the content ahead of the specified conref, you reverse the mark and conaction steps (conaction comes first). Also, you must specify conaction=”pushbefore”. Assuming the same input and output as the previous example, this is how to insert step 3 before step 4:

<task id=”pushing-task”>
...
    <steps>
    <step conaction=”pushbefore”>
    <cmd>Third command</cmd>
    </step>
    <step conaction=”mark”>
conref=”source-task.dita#source-task/fourth-step”
    />
    ...

Conkeyref

The conref attribute that is used in older DITA versions requires a direct reference. In the previous example, a file “source-task.dita” is specified:

conref=”source-task.dita#source-task/fourth-step” This is long and cumbersome. Also, if you were to rename source-task.dita, you would have to change all references to source-task.dita.

Conkeyref allows you to add a layer of abstraction, so instead of specifying a direct reference that has a file name, you can specify a key: conkeyref=“source-task-key/fourth-step”

But how does the key point to the actual DITA file? To do that, add a to the DITA map, as in this example file named HowToUseLCDTVGuide.ditamap:

<map>
<title>How to use your LCD TV</title>
<keydef
keys="source-task-key"
href="source-task.dita"
type="topic" format="dita"
/>
...

Glossaries and abbreviations

DITA 1.1 glossary topics only allowed terms and definitions. The good news is that beginning with DITA 1.2, glossary topics allow alternate terms such as acronyms, synonyms, and a short form. They also allow new usage information such as properties, status, and scope. Here is an example of a glossary entry that uses many of the new options:

<glossentry id="lcdtv">
<glossterm>LCD Television</glossterm>
<glossdef>A TV whose display is made of liquid crystal.</glossdef>
<glossBody>
<glossSurfaceForm>
Liquid Crystal Display Television (LCD TV)
</glossSurfaceForm>
<glossPartOfSpeech value="noun"/>
<glossUsage>Don’t confuse LCD with LED</glossUsage>
<glossAlt>
<glossAbbreviation>flat display</glossAbbreviation>
<glossStatus value="prohibited"/>
<glossUsage>
Non-specific because it includes LED and plasma.
</glossUsage>
</glossAlt>
</glossBody>
</glossentry>

The key must be associated with a topic:

<keydef keys=“lcdtv” href=“all-about-lcdtv.dita”/>

Now it can be used in the content. Acronyms can be automatically expanded using <abbreviated-form>:

<p>You will love your <abbreviated-form keyref=“lcdtv”/> from the moment you open the box.</p>
<p>Tell your friends about your <abbreviated-form keyref=“lcdtv”/>.</p>

 

The first usage displays the <glossSurfaceForm>, and subsequent usages display just the acronym:

You will love your Liquid Crystal Display Television (LCD TV) from the moment you open the box.
Tell your friends about your LCD TV.

Learning and training

If you are involved in developing instructional materials then you will love DITA 1.2 because it includes several modules created by the DITA Learning Subcommittee, experts in the learning field. These include several specializations of topics and tasks used to design information related to learning activities.

In today’s complex world where there are many interrelated bits and pieces of information, and many different ways to access that information, developers of learning and training content face many challenges, including:

  • How to find the context for developing and delivering the right content to the right person at the right time?
  • How to identify the learning goals and objectives?
  • Who is the audience and how big is it? How to pull together and integrate content from many different sources and content providers?
  • How to enable customers and partners to add, integrate, assemble and deliver their own content?
  • DITA 1.2 addresses these issues by providing:
  • Reuse for Reusable Learning Objects (RLO)
  • Topic types as building blocks for learning objects
  • Domains to provide the mechanism for interactions and metadata
  • Maps to arrange learning topics into lessons, modules and courses
  • Specialization for learning-based topic types, domains and maps

 

Machinery-based specializations

If you write machinery-task based documents targeting the machine industry, you will be pleased to know that DITA 1.2 supports your efforts. This type of document is built by combining the general task information type with the Task Requirements Domain and the Machinery Taskbody Constraint. It contains special task requirement elements, and is based on S1000D elements.

Created by the OASIS DITA Machinery Subcommittee, this specification provides procedural information, similar to other task types. Its well-defined semantic structure is designed to meet the special requirements of organizations that develop instructional material for industrial equipment, such as industrial products like trucks, mining machinery and automobiles. The machine-industry task requirements domain adds several new descriptive elements in the preliminary requirements (prelreqs) and closing requirements (closereqs) sections. Caution and warning notes based on ANSI are integrated into the core modules:

<note type=“caution1”>
<note type=“caution2”>
<note type=“danger”>

Mapping groups using <topicset> and<topicssetref>

The new <topicset> element enables you to define a branch of navigation in a DITA map so that it can be referenced from another DITA map. The new <topicsetref> element enables you to reference a navigation branch that is defined in another DITA map.

The primary purpose of the new convenience <topicset> element is to define a group of topics that generally stay together as a unit. You might want to use these tasks in many places, but you will always use them as a group.

In this example, our LCD TV help has a DITA map named lcd_tv_help.ditamap containing a <topicset> that will stay together no matter where it is used:

<map title=”LCD TV Help”>
    <topicref format=”dita” href=”LCD_TV_Help.dita”>
    <topicset id=”installing-lcdtv” href=”Installing.dita”>
    <topicref href=”Unpacking_LCDTV.dita” />
    <topicref href=”Cabling_LCDTV.dita” />
    …
    </topicset>
    …

Now the topic set can be referred to by a DITA map named lcd_tv_quick_start.ditamap containing <topicsetref>:

<map title=”LCD TV Quick Start”>
    <mapref href=”why_you_will_love_your_LCD_TV.dita”>
    <mapref href=”why_your_neighbors_will_love_your_LCD_TV.dita”>
    <topicsetref href=”lcd_tv_help.ditamap#installing-lcdtv”>
</map>

<map title="”LCD"><mapref href="”why_you_will_love_your_LCD_TV.dita”"><mapref href="”why_your_neighbors_will_love_your_LCD_TV.dita”"><topicsetref href="”lcd_tv_help.ditamap#installing-lcdtv”"></topicsetref></mapref></mapref></map>

Subjects and schemes

A new specialized DITA map element named <subjectScheme> allows you to define subjects and relationships. This is handy when you need to define a taxonomy, such as a collection of controlled values allowed in an attribute. Subjects may be associated with topics in other maps, which provide metadata that can be used to improve searching.

Each controlled value is defined using a specialized topic reference, called <subjectdef>. The <subjectdef> is used to define both a category and a list of controlled values.

The top-level <subjectdef> defines the category and the children define the controlled values. The following example illustrates the use of <subjectdef> to define what possible audiences are allowed for an LCD TV. Note how they can be nested (end user can be a novice or an expert):

<subjectScheme>
<subjectdef keys="users">
<subjectdef keys="enduser">
<subjectdef keys="novice"/>
<subjectdef keys="expert"/>
</subjectdef>
<subjectdef keys="salesperson">
<subjectdef keys="techsupport">
</subjectdef>
<enumerationdef>
<attributedef name="audience"/>
<subjectdef keyref="users"/>
</enumerationdef>
</subjectScheme>

There are advanced elements available that specify the kind of relationship in a hierarchy between a container subject and its contained subjects: <hasNarrower>, <hasPart>, <hasKind>, <hasInstance> and <hasRelated> elements. These can be leveraged by sophisticated tools to make intelligent associations between the content.

Constraints

Constraints empower DTD and Schema developers to restrict content models, such as removing text and phrases from<section> elements. This allows an organization to simplify what the author sees without the need to create a specialization.

Typical restrictions include limiting the content model, attributes for an element, and extension elements from a domain. Replacing base elements by domain extensions is common.

However, to do this requires knowledge of the schema (DTD/XSD) to implement the constraint. Note that if you use an authoring tool that supports DTDs or Schemas, that tool has basic constraint support.

Other features

Reltable headers

Reltables now often set types for each column. Relationship tables are defined with the <reltable> element. Relationship tables can be used to define relationships between DITA topics or between DITA topics and non-DITA resources.

In DITA 1.2 you can add a title to the header by inserting a topicref. Links to topics in that column will be grouped under a heading determined by that topic.

<sectiondiv>

An untitled alternative to nested sections

<bodydiv>

This is similar to <sectiondiv> because it allows grouping of sections or other body content without allowing sections.

<text>

This allows semantic-free reuse of small pieces of text, but is restricted to locations that do not allow semantic elements.

<coderef>

Allows you to include text verbatim, such as source code.

Misc

  • Image scaling
  • Removed several attribute enumerations
  • Expanded use of draft-comment in <body> and <shortdesc>
  • New map elements <mapref>, <topicset>, and more

Conclusion

DITA 1.2 is an exciting upgrade to DITA 1.1 that has a lot to offer and is worth investigating. You will find several useful links listed below which can  help you learn even more about DITA 1.2.

References