DITA for the Impatient

Hussein Shafie
September 18, 2013
Pixware

Table of Contents

1. Introduction

2. About topics and maps

3. The topic element

4. Specialized topic types

5. Topic maps

6. Conclusion

1. Introduction Previous topic Parent topic Child topic Next topic

By reading this short tutorial, you'll get acquainted with the DITA Opens in new window markup and after that, you'll be able to author your first DITA document(1) right away.
This short tutorial will not discuss the DITA ``philosophy'' or the advantages of the DITA vocabulary over other XML vocabularies (e.g. DocBook Opens in new window).
This article is published under the Creative Commons "Attribution-Share Alike" Opens in new window license.

2. About topics and maps Previous topic Parent topic Child topic Next topic

A DITA document is necessarily modular. The information unit used to compose a DITA document is called a topic. As its name suggests it, a topic addresses a single subject.
The overall contents of a DITA document is specified using a topic map (also simply called a map). A map mainly contains a hierarchy of topic references.

Figure 1. File layout of this tutorial

file_layout.png
Remember
Remember
  • It is recommended to have a single topic per XML file.
  • The recommended filename extension for a topic file is ".dita".
  • The recommended filename extension for a map file is ".ditamap".
  • Topic and map files may be contained in different directories. You are free to organize the contents of these directories as you wish.

3. The topic element Previous topic Parent topic Child topic Next topic

In this chapter,

3.1. The structure of the topic element Previous topic Parent topic Child topic Next topic

Remember
Remember
A topic element must always be given an ID. Use the id attribute to specify it.
The structure of the topic Opens in new window element is very simple:
  1. A title Opens in new window element.
  2. An optional shortdesc Opens in new window or abstract Opens in new window element.
    The shortdesc element is longer and more descriptive than the title element. However, it is recommended to keep it short, approximately one paragraph long, because the contents of this element is often used during navigation (e.g. to generate a detailed table of contents).
    The abstract element is intended to contain more information than the shortdesc element.
  3. A body Opens in new window element(2).
  4. An optional related-links Opens in new window element.
    This is a kind of ``See Also'' section containing a list of link Opens in new window elements. Topics being generally short, this section stands out clearly after the body of a topic. That's why it is often preferred to spreading links inside the body of a topic.
Example:
<topic id="docbook_or_dita">
  <title>DITA or DocBook?</title>

  <shortdesc>Both DITA and DocBook are both mature, feature rich, document types,
  so which one to choose?</shortdesc>

  <body>
    <p>DocBook 5 is a mature document type, well-documented (DocBook: The
    Definitive Guide, DocBook XSL: The Complete Guide), coming with decent XSL
    stylesheets allowing to convert it to a variety of formats, based on the
    best schema technologies: RELAX NG and Schematron.</p>

    <p>DITA concepts (topics, maps, specialization, etc) have an immediate
    appeal to the technical writer and indeed, makes this document type more
    attractive than DocBook. However the DocBook vocabulary is comprehensive
    and very well thought. So choose DITA if its standard vocabulary is
    sufficiently expressive for your needs or if, anyway, you intend to
    specialize DITA.</p>
  </body>

  <related-links>
    <link format="html" href="http://www.docbook.org/" scope="external">
      <linktext>DocBook 5</linktext>
    </link>

    <link format="html"
          href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita"
          scope="external">
      <linktext>DITA</linktext>
    </link>
  </related-links>
</topic>
The above example is rendered as follows:

DITA or DocBook?

Both DITA and DocBook are both mature, feature rich, document types, so which one to choose?

DocBook 5 is a mature document type, well-documented (DocBook: The Definitive Guide, DocBook XSL: The Complete Guide), coming with decent XSL stylesheets allowing to convert it to a variety of formats, based on the best schema technologies: RELAX NG and Schematron.
DITA concepts (topics, maps, specialization, etc) have an immediate appeal to the technical writer and indeed, makes this document type more attractive than DocBook. However the DocBook vocabulary is comprehensive and very well thought. So choose DITA if its standard vocabulary is sufficiently expressive for your needs or if, anyway, you intend to specialize DITA.

3.2. The most commonly used “block elements” Previous topic Parent topic Child topic Next topic

The most commonly used block elements are borrowed from HTML and as such, should be immediately familiar to the reader.

Paragraphs and lists

A paragraph is represented by the p Opens in new window element.
A preformatted paragraph is represented by the pre Opens in new window element.
An itemized list is represented by the ul Opens in new window element. As expected, it contains li Opens in new window list item elements.
An ordered list is represented by the ol Opens in new window element.
A variable list is represented by the dl Opens in new window element. Unlike HTML's dl, the dt Opens in new window (term being defined) and the dd Opens in new window (term definition) elements must be wrapped in a dlentry Opens in new window element.
Example:
<ul>
  <li>First item.
    <p>Continuation paragraph.</p>
  </li>

  <li>Second item. This item contains an ordered list.
    <ol>
      <li>First do this.</li>
      <li>Then do that.</li>
      <li>Finally do this.</li>
    </ol>
  </li>

  <li>Third item. This item contains a variable list.
    <dl>
      <dlentry>
        <dt>Term #1</dt>
        <dd>Definition of term #1.</dd>
      </dlentry>

      <dlentry>
        <dt>Term #2</dt>
        <dd>Definition of term #2.</dd>
      </dlentry>
    </dl>
  </li>
</ul>
The above example is rendered as follows:
  • First item.
    Continuation paragraph.
  • Second item. This item contains an ordered list.
    1. First do this.
    2. Then do that.
    3. Finally do this.
  • Third item. This item contains a variable list.
    Term #1
    Definition of term #1.
    Term #2
    Definition of term #2.

Sections

DITA has no h1, h2, h3, etc, heading elements. Instead it has the section Opens in new window element which generally always has a title Opens in new window child element. Note that section elements cannot nest. Example:
<section>
  <title>The customary “hello word” program in Tcl/Tk</title>

  <pre frame="all">button .hello -text "Hello, World!" -command { exit }
       pack .hello</pre>
</section>
The above example is rendered as follows:

The customary “hello word” program in Tcl/Tk

button .hello -text "Hello, World!" -command { exit }
pack .hello

Figures and examples

Of course, DITA has also figure, table and example elements.
The example Opens in new window element is just a specialized kind of section.
The fig Opens in new window element generally has a title and generally contains an image element.
Like img, its HTML counterpart, the image Opens in new window “inline element” may be contained in any “block element”. The graphics file which is to be displayed is specified using the href attribute. The image element also has width, height, scale and align attributes.
Example:
<example>
  <title>Converting a color image to black and white</title>

  <pre>$ convert -dither Floyd-Steinberg -monochrome photo.png bwphoto.gif</pre>

  <fig>
    <title>The photo converted to black and white</title>
    <image href="bwphoto.gif" align="center"/>
  </fig>
</example>
The above example is rendered as follows:

Converting a color image to black and white

$ convert -dither Floyd-Steinberg -monochrome photo.png bwphoto.gif

Figure 2. The photo converted to black and white

bwphoto.gif

Tables

DITA has two kinds of table element: simpletable Opens in new window which is specific to DITA, and table Opens in new window which is in fact a CALS Opens in new window table (also know as a DocBook table).
Simpletable example:
<simpletable relcolwidth="1* 2* 3*">
  <sthead>
    <stentry>A</stentry>
    <stentry>B</stentry>
    <stentry>C</stentry>
  </sthead>

  <strow>
    <stentry>A,1</stentry>
    <stentry>B,1</stentry>
    <stentry>C,1</stentry>
  </strow>

  <strow>
    <stentry>A,2</stentry>
    <stentry>B,2</stentry>
    <stentry>C,2</stentry>
  </strow>
</simpletable>
A simpletable element contains an optional sthead Opens in new window element, followed by one or more strow Opens in new window elements. Both row elements, sthead and strow, contain stentry Opens in new window cell elements. The relcolwidth attribute may be used to specify the relative width of each column.
The above example is rendered as follows:
A B C
A,1 B,1 C,1
A,2 B,2 C,2
Same as above example but using a CALS table this time:
<table>
  <title>Sample CALS table</title>

  <tgroup cols="3">
    <colspec colwidth="1*"/>
    <colspec colwidth="2*"/>
    <colspec colwidth="3*"/>

    <thead>
      <row>
        <entry align="center">A</entry>
        <entry align="center">B</entry>
        <entry align="center">C</entry>
      </row>
    </thead>

    <tbody>
      <row>
        <entry>A,1</entry>
        <entry>B,1</entry>
        <entry>C,1</entry>
      </row>

      <row>
        <entry>A,2</entry>
        <entry>B,2</entry>
        <entry>C,2</entry>
      </row>
    </tbody>
  </tgroup>
</table>
CALS tables are quite complex and explaining how they can be used is out of the scope of this tutorial. Our recommendation is to use CALS tables rather than simpletables only when you want a cell to span more than one row and/or more than one column.
The above example is rendered as follows:

Table 1. Sample CALS table

A B C
A,1 B,1 C,1
A,2 B,2 C,2

3.3. The most commonly used “inline elements” Previous topic Parent topic Child topic Next topic

The most generic inline elements are also borrowed from HTML: i Opens in new window (italic), b Opens in new window (bold), tt Opens in new window (teletype or monospaced text), sub Opens in new window (subscript), sup Opens in new window (superscript).
However like with any other document type, you should always try to use the most specific element for your needs. Examples:
DITA has dozens of such useful inline elements. In order to use them, we recommend authoring your documents with a DITA aware XML editor and browsing through the element names suggested by the editor. Generally these names are very descriptive, so there is no real need to read the documentation.
Remember
Remember
Using the most specific elements rather than the generic i, b, tt elements, means getting nicer deliverables.
Example: Let's suppose you want to refer to the "Open" item of the "File" menu. Do not type <tt>File->Open</tt> which would be rendered as: File->Open. Instead type <menucascade><uicontrol>File</uicontrol><uicontrol>Open</uicontrol></menucascade>, which will be rendered as: FileOpen. Much nicer, isn't it?

4. Specialized topic types Previous topic Parent topic Child topic Next topic

The topic Opens in new window element is the most generic topic type. There are four more specialized topic types: concept Opens in new window, task Opens in new window, reference Opens in new window, glossentry Opens in new window. When appropriate, use a specialized topic type rather than a plain topic.

4.1. The concept element Previous topic Parent topic Child topic Next topic

Create a concept Opens in new window element when you need to provide your reader with background information which must be absorbed in order to understand the rest of the document.
Example:
<concept id="what_is_a_cache">
  <title>What is a cache?</title>

  <shortdesc>Everything you'll ever need to know about
  <term>cache</term>s.</shortdesc>

  <conbody>
    <p>In computer science, a cache is a temporary storage area where
    frequently accessed data can be stored for rapid access.</p>
  </conbody>

  <related-links>
    <link format="html" href="http://en.wikipedia.org/wiki/Cache"
          scope="external">
      <linktext>Wikipedia definition of a cache</linktext>
    </link>
  </related-links>
</concept>
Notice how the structure of a concept element is similar to the structure of a topic element. Moreover, a conbody Opens in new window element has almost the same content model as a body Opens in new window element.
The above example is rendered as follows:

What is a cache?

Everything you'll ever need to know about caches.

In computer science, a cache is a temporary storage area where frequently accessed data can be stored for rapid access.

4.2. The task element Previous topic Parent topic Child topic Next topic

Create a task Opens in new window element when you need to explain step by step which procedure is to be followed in order to accomplish a given task.
Example:
<task id="install_emacs">
  <title>Installing GNU Emacs</title>

  <taskbody>
    <prereq>Windows NT 4.0 or any subsequent version of Windows. 5Mb of free
    disk space.</prereq>

    <steps>
      <step>
        <cmd>Unzip the distribution anywhere.</cmd>

        <info>We recommend to use the free, open source, <xref format="html"
        href="http://www.info-zip.org/" scope="external">Info-ZIP</xref>
        utility to do so.</info>

        <stepxmp><screen>C:\&gt; unzip emacs-21.3-bin-i386.zip</screen></stepxmp>

        <stepresult><p>Doing this will create an
        <filepath>emacs-21.3</filepath> directory.</p></stepresult>
      </step>

      <step>
        <cmd>Go to the bin subdirectory.</cmd>

        <stepxmp><screen>C:\&gt; cd emacs-21.3\bin</screen></stepxmp>
      </step>

      <step>
        <cmd>Run <cmdname>addpm</cmdname>.</cmd>

        <stepxmp><screen>C:\emacs-21.3\bin&gt; addpm</screen></stepxmp>

        <stepresult>A confirmation dialog box is displayed.<fig>
            <image href="confirm_install_emacs.png"/>
          </fig></stepresult>
      </step>

      <step>
        <cmd>Click <uicontrol>OK</uicontrol> to confirm.</cmd>
      </step>
    </steps>
  </taskbody>
</task>
Albeit being the most complex specialized topic type, the task element is also the most useful one. Its taskbody Opens in new window is mainly organized around the steps Opens in new window element. Other useful elements are prereq Opens in new window (pre-requisite section of a task), context Opens in new window (background information for the task), result Opens in new window (expected outcome of a task).
The step Opens in new window element has several useful child elements other than the required cmd Opens in new window element: info Opens in new window (additional information about the step), stepxmp Opens in new window (example that illustrates a step), substeps Opens in new window, choices Opens in new window (the user needs to choose one of several actions), stepresult Opens in new window (expected outcome of a step).
The above example is rendered as follows:

Installing GNU Emacs

Before you begin

Windows NT 4.0 or any subsequent version of Windows. 5Mb of free disk space.

Procedure

  1. Unzip the distribution anywhere.
    We recommend to use the free, open source, Info-ZIP Opens in new window utility to do so.
    C:\> unzip emacs-21.3-bin-i386.zip
    Doing this will create an emacs-21.3 directory.
  2. Go to the bin subdirectory.
    C:\> cd emacs-21.3\bin
  3. Run addpm.
    C:\emacs-21.3\bin> addpm
    A confirmation dialog box is displayed.
    confirm_install_emacs.png
  4. Click OK to confirm.

4.3. The reference element Previous topic Parent topic Child topic Next topic

Create a reference Opens in new window element when you need to add an entry to a reference manual. The reference element is typically used to document a command or a function.
Example:
<reference id="pwd_command">
  <title>The <cmdname>pwd</cmdname> command</title>

  <refbody>
    <refsyn><cmdname>pwd</cmdname></refsyn>

    <section><title>DESCRIPTION</title><p>Print the full filename of the
    current working directory.</p><note>Your shell may have its own version of
    <cmdname>pwd</cmdname>, which usually supersedes the version described
    here.</note></section>

    <section><title>AUTHOR</title><p>Written by John Doe. </p></section>
  </refbody>

  <related-links>
    <link format="html" href="http://www.manpagez.com/man/3/getcwd/"
          scope="external">
      <linktext><cmdname>getcwd</cmdname>(3)</linktext>
    </link>
  </related-links>
</reference>
The refbody Opens in new window child element of a reference can contain the following generic elements: section Opens in new windows, example Opens in new windows, simpletable Opens in new windows and table Opens in new windows but also more specific elements: refsyn Opens in new window (contains the syntax of a command-line utility or the prototype of a function) and properties Opens in new window (a special kind of table having 3 columns: type, value and description).
The above example is rendered as follows:

The pwd command

pwd

DESCRIPTION

Print the full filename of the current working directory.
Note
Note
Your shell may have its own version of pwd, which usually supersedes the version described here.

AUTHOR

Written by John Doe.

4.4. The glossentry element Previous topic Parent topic Child topic Next topic

Create a glossentry Opens in new window element when you need to add entry to a glossary.
The following example shows three glossary entries having the following IDs: ajax, dhtml, javascript.
<glossgroup id="sample_glossary">
  <title>Sample glossary</title>

  <glossentry id="ajax">
    <glossterm>AJAX</glossterm>

    <glossdef><b>A</b>synchronous <b>Ja</b>vaScript and <b>X</b>ML. Web
    development techniques used on the client-side to create interactive web
    applications.</glossdef>
  </glossentry>

  <glossentry id="dhtml">
    <glossterm>DHTML</glossterm>

    <glossdef><b>D</b>ynamic <b>HTML</b>. Web development techniques used on
    the client-side to create interactive web sites.</glossdef>
  </glossentry>

  <glossentry id="javascript">
    <glossterm>JavaScript</glossterm>

    <glossdef>JavaScript is an object-oriented scripting language supported by
    all major web browsers. It allows the development of interactive web sites
    and web applications.</glossdef>

    <related-links>
      <link format="html" href="https://developer.mozilla.org/en/JavaScript"
            scope="external">
        <linktext>Mozilla's Official Documentation on JavaScript</linktext>
      </link>
    </related-links>
  </glossentry>
</glossgroup>
The glossentry element is the simplest specialized topic type. It contains a glossterm Opens in new window child element (the term being defined) followed by a glossdef Opens in new window (the definition of the term) child element, optionally followed by the related-links Opens in new window element common to all topic types.
In the above example, the glossgroup Opens in new window element is used as a container for the three glossentry elements.
Remember
Remember
  • It is not recommended to create XML files containing several topics because if you do so, first this makes it harder reusing your topics in different documents and second, this makes the topic map slightly harder to specify.
    However if you need to create multi-topic files, you'll have to use the dita Opens in new window element as a wrapper for your topics.
  • A topic may contain other topics. The DITA grammar allows to add a topic child element after the body or related-links element (whichever is the last child) of the parent topic.
    It is not recommended to use this nested topics facility which, in our opinion, is almost never useful. The hierarchy of topics (that is, chapters containing sections containing subsections, etc) is better expressed in a map using a hierarchy of topicrefs(3).
The above example is rendered as follows:

Sample glossary

AJAX
Asynchronous JavaScript and XML. Web development techniques used on the client-side to create interactive web applications.
DHTML
Dynamic HTML. Web development techniques used on the client-side to create interactive web sites.
JavaScript
JavaScript is an object-oriented scripting language supported by all major web browsers. It allows the development of interactive web sites and web applications.

5. Topic maps Previous topic Parent topic Child topic Next topic

5.1. The map element Previous topic Parent topic Child topic Next topic

A topic map Opens in new window mainly contains:
The href attribute of a topicref element specifies the URL of a topic which is part of the DITA document. Example:
<topicref href="samples/sample_glossary.dita"/>
If the target XML file contains several topics (not recommended), you'll have to use a fragment to specify the ID of the referenced topic.
<topicref href="samples/sample_glossary.dita#javascript"/>
A map contains a hierarchy of topicref elements. What does this mean?
<topicref href="topic.dita">
  <topicref href="topic_structure.dita">
    <topicref href="samples/sample_topic.dita"/>
  </topicref>
  <topicref href="block_elements.dita"/>
  <topicref href="inline_elements.dita"/>
  <topicref href="link_elements.dita"/>
</topicref>
In the case of the above example, this means two things:
  1. The overall DITA document contains this sequence of topics: topic.dita, topic_structure.dita, samples/sample_topic.dita, block_elements.dita, inline_elements.dita, link_elements.dita.
  2. Topics topic_structure.dita, block_elements.dita, inline_elements.dita, link_elements.dita are subsections of topic topic.dita. Topic samples/sample_topic.dita is a subsection of topic topic_structure.dita.
    If you instruct the DITA processing software to generate a Table of Contents for your document and/or to number the topics, the hierarchy of topics appears very clearly.
What follows is the topic map actually used for this tutorial (contents of file tutorial.ditamap Opens in new window):
<map>
  <title>DITA for the Impatient</title>

  <topicmeta>
    <author>Hussein Shafie</author>
    <publisher>Pixware</publisher>
    <critdates>
      <created date="October 7, 2009"/>
    </critdates>
  </topicmeta>

  <topicref href="introduction.dita"/>
  <topicref href="topics_and_maps.dita"/>
  <topicref href="topic.dita">
    <topicref href="topic_structure.dita">
      <topicref href="samples/sample_topic.dita" toc="no"/>
    </topicref>
    <topicref href="block_elements.dita"/>
    <topicref href="inline_elements.dita"/>
    <topicref href="link_elements.dita"/>
  </topicref>
  .
  .
  .
  <topichead navtitle="Topic maps">
    <topicref href="map.dita"/>
    <topicref href="bookmap.dita"/>
  </topichead>
  <topicref href="conclusion.dita"/>
</map>

The toc attribute

Specifying attribute toc="no" for a topicref element allows to prevent it from appearing in the generated Table of Contents.
    <topicref href="topic_structure.dita">
      <topicref href="samples/sample_topic.dita" toc="no"/>
    </topicref>

The topichead element

The topichead Opens in new window element provides an author with a simple way to group several topics in the same HTML page and to give this HTML page a title(4).
  <topichead navtitle="Topic maps">
    <topicref href="map.dita"/>
    <topicref href="bookmap.dita"/>
  </topichead>

5.2. The bookmap element Previous topic Parent topic Child topic Next topic

A bookmap Opens in new window element is just a more elaborate form of map Opens in new window. We recommend using a bookmap for anything more complex than an article.
Tip
Tip
You don't need to create a map for the screen media and a bookmap for the print media. If you follow the “one topic per XML file” rule, a single topic map (map or bookmap depending on the complexity of the contents) is all what you need.
What follows is a possible bookmap for this tutorial (contents of file tutorial-book.ditamap Opens in new window):
<bookmap>
  <booktitle>
    <mainbooktitle>DITA for the Impatient</mainbooktitle>
  </booktitle>

  <bookmeta>
    <authorinformation>
      <personinfo>...</personinfo>
      <organizationinfo>...</organizationinfo>
    </authorinformation>
    <critdates>
      <created date="October 7, 2009"/>
    </critdates>
  </bookmeta>

  <frontmatter>
    <booklists>
      <toc/>
      <figurelist/>
      <tablelist/>
    </booklists>
  </frontmatter>

  <chapter href="introduction.dita"/>
  <chapter href="topics_and_maps.dita"/>
  <chapter href="topic.dita">
    <topicref href="topic_structure.dita">
      <topicref href="samples/sample_topic.dita" toc="no"/>
    </topicref>
    <topicref href="block_elements.dita"/>
    <topicref href="inline_elements.dita"/>
    <topicref href="link_elements.dita"/>
  </chapter>
  .
  .
  .
  <chapter navtitle="Topic maps">
    <topicref href="map.dita"/>
    <topicref href="bookmap.dita"/>
  </chapter>
  <chapter href="conclusion.dita"/>
</bookmap>

6. Conclusion Previous topic Parent topic Child topic Next topic

This tutorial has just scratched the surface of DITA. We didn't discuss:
However we believe that what you have learned here is sufficient to start authoring your first DITA document.

 (1) Preferably using a DITA-aware XML editor such as XMLmind XML Editor Opens in new window.
 (2) The body element is optional too. However creating a topic element having no body child element is mainly a trick which is more simply implemented by adding a topichead Opens in new window to a map.
 (3) More about topic maps later in this tutorial.
 (4) A less convenient alternative would be to use an actual topic having no body at all, just a title.