A Tour of DITA

A shallow, practical look at how DITA structures content: topics, reuse, and maps, shown through terse fragments rather than complete topics. Under the hood, DITA 1.3 defines 182 elements in its base vocabulary and 610 overall once specializations and domains are included, but few authors need most of them: most start with a small, common set and adopt more only as their content needs more specific markup. For the full language reference, see Specifications.

Note: Each fragment comes with an example rendition. Published output depends on DITA processor and custom styling.

Topic Types

DITA content is written in typed topics. Each type specializes the base <topic> element for a specific kind of content.

Concept

A <concept> explains background information a reader needs to understand before acting.

<concept id="disk_management">
  <title>Disk Management</title>
  <shortdesc>Disk management lets you partition, format, and monitor
    storage devices.</shortdesc>
  <conbody>
    <p>A disk must be partitioned before it can be formatted.</p>
  </conbody>
</concept>

Disk Management

Disk management lets you partition, format, and monitor storage devices.

A disk must be partitioned before it can be formatted.

Task

A <task> walks a reader through the steps needed to accomplish a goal.

<task id="format_disk">
  <title>Formatting a Disk</title>
  <shortdesc>Format a disk to prepare it for use.</shortdesc>
  <taskbody>
    <context>
      <p>Formatting erases all data on the disk.</p>
    </context>
    <steps>
      <step>
        <cmd>Select the disk.</cmd>
      </step>
      <step>
        <cmd>Click <uicontrol>Format</uicontrol>.</cmd>
        <stepresult>The disk is formatted with the default file system.</stepresult>
      </step>
    </steps>
    <result>
      <p>The disk is ready to store files.</p>
    </result>
  </taskbody>
</task>

Formatting a Disk

Format a disk to prepare it for use.

Formatting erases all data on the disk.

  1. Select the disk.

  2. Click Format.

    The disk is formatted with the default file system.

The disk is ready to store files.

Reference

A <reference> presents lookup information, such as command syntax or property tables.

<reference id="disk_commands">
  <title>Disk Commands</title>
  <shortdesc>Command-line utilities for managing disks.</shortdesc>
  <refbody>
    <refsyn>
      <pre>diskutil &lt;command&gt; [device]</pre>
    </refsyn>
    <section>
      <title>Commands</title>
      <simpletable>
        <sthead>
          <stentry>Command</stentry>
          <stentry>Description</stentry>
        </sthead>
        <strow>
          <stentry>list</stentry>
          <stentry>Lists available disks.</stentry>
        </strow>
      </simpletable>
    </section>
  </refbody>
</reference>

Disk Commands

Command-line utilities for managing disks.

diskutil <command> [device]

Commands

CommandDescription
listLists available disks.

Common Elements

Paragraph and Short Description

A <shortdesc> is a one- or two-sentence summary used in generated previews and search results.

<shortdesc>A short summary of the topic, used in search results and
  previews.</shortdesc>

A short summary of the topic, used in search results and previews.

<p> is a normal paragraph.

<p>A regular paragraph of body text.</p>

A regular paragraph of body text.

Section

<section> groups related content under an optional title within a topic body.

<section>
  <title>Prerequisites</title>
  <p>Back up your data before continuing.</p>
</section>

Prerequisites

Back up your data before continuing.

<example> is similar, but specifically for example content. Without a <title>, it can get an autogenerated title.

<example>
  <p>Running <cmdname>diskutil list</cmdname> shows all disks and
    partitions.</p>
</example>

Example

Running diskutil list shows all disks and partitions.

Inline Elements

DITA has many inline elements for marking up text by what it means, rather than how it should look. <filepath> and <menucascade> are two examples, among many: <filepath> marks a file or directory name, and <menucascade> groups a sequence of <uicontrol> menu selections.

<p>Open <filepath>/Applications/Utilities/Disk Utility.app</filepath>,
  then choose <menucascade><uicontrol>File</uicontrol><uicontrol>New
  Image</uicontrol></menucascade>.</p>

Open /Applications/Utilities/Disk Utility.app, then choose File > New Image.

Lists

<ul> and <ol> create bulleted and numbered lists of <li> items.

<ul>
  <li>Coffee</li>
  <li>Tea</li>
</ul>
  • Coffee
  • Tea
<ol>
  <li>Boil water.</li>
  <li>Add tea leaves.</li>
</ol>
  1. Boil water.
  2. Add tea leaves.

<dl> pairs terms (<dt>) with descriptions (<dd>), grouped in <dlentry> elements.

<dl>
  <dlentry>
    <dt>API</dt>
    <dd>Application Programming Interface.</dd>
  </dlentry>
</dl>
API
Application Programming Interface.

Admonition

<note> flags supplementary information. The type attribute selects a built-in kind, such as warning, tip, or danger.

<note type="warning">Formatting a disk erases all data on it.</note>
Warning: Formatting a disk erases all data on it.

Image and Figure

<image> embeds an image. Wrap it in <fig> to add a caption.

<fig>
  <title>Disk Utility Window</title>
  <image href="disk-utility.png" alt="The Disk Utility window"/>
</fig>
The Disk Utility window
Figure 1: Disk Utility Window

Table

<simpletable> is a lightweight table of rows and columns.

<simpletable>
  <sthead>
    <stentry>Name</stentry>
    <stentry>Type</stentry>
  </sthead>
  <strow>
    <stentry>disk0</stentry>
    <stentry>SSD</stentry>
  </strow>
</simpletable>
NameType
disk0SSD

<table> is the full CALS-style table model, built from a <tgroup> of <colspec> columns. An entry spans columns with namest/nameend, and spans rows with morerows.

<table>
  <tgroup cols="3">
    <colspec colname="c1"/>
    <colspec colname="c2"/>
    <colspec colname="c3"/>
    <thead>
      <row>
        <entry namest="c1" nameend="c2">Disk</entry>
        <entry>Status</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry morerows="1">disk0</entry>
        <entry>Partition 1</entry>
        <entry>Healthy</entry>
      </row>
      <row>
        <entry>Partition 2</entry>
        <entry>Healthy</entry>
      </row>
    </tbody>
  </tgroup>
</table>
DiskStatus
disk0Partition 1Healthy
Partition 2Healthy

Cross-Reference and Link

<xref> links to another topic, an element within a topic, or an external URL.

<p>
  See <xref href="disk_management.dita"/> for background. An external
  resource <xref href="https://example.com" scope="external"
                 format="html">Example</xref>.
</p>

See Disk Management for background. An external resource Example.

<related-links> lists <link> elements pointing to other topics, rendered at the end of a topic. Without <linktext>, the link uses the target topic’s title.

<related-links>
  <link href="format_disk.dita" role="child">
    <linktext>Formatting a Disk</linktext>
  </link>
  <link href="disk_commands.dita" role="sibling"/>
</related-links>

Related Links

Related links can also be defined centrally in a map, using <reltable>, instead of <related-links> in each topic.

Code Block

<codeblock> marks a block of preformatted code. <pre> marks other preformatted text, such as command syntax.

<codeblock outputclass="language-sh">diskutil list</codeblock>
diskutil list

Task-Specific Elements

<steps> holds an ordered sequence of <step> elements, each with a command (<cmd>), an optional explanation (<info>), and an optional result (<stepresult>).

<steps>
  <step>
    <cmd>Open Disk Utility.</cmd>
  </step>
  <step>
    <cmd>Select the disk, then click <uicontrol>Erase</uicontrol>.</cmd>
    <info>This step permanently deletes all data on the disk.</info>
    <stepresult>The disk is erased and ready to format.</stepresult>
  </step>
</steps>

Steps

  1. Open Disk Utility.

  2. Select the disk, then click Erase.

    This step permanently deletes all data on the disk.

    The disk is erased and ready to format.

Reference-Specific Elements

<properties> lists name/value pairs, such as command options or configuration settings, each with an optional description.

<properties>
  <prophead>
    <proptypehd>Option</proptypehd>
    <propvaluehd>Value</propvaluehd>
    <propdeschd>Description</propdeschd>
  </prophead>
  <property>
    <proptype>-v</proptype>
    <propvalue>verbose</propvalue>
    <propdesc>Prints detailed output.</propdesc>
  </property>
</properties>
OptionValueDescription
-vverbosePrints detailed output.

Maps

A map assembles topics into a navigable structure and defines relationships between them, without containing content of its own. <topichead> groups topic references under a heading that doesn’t correspond to an actual topic.

<map>
  <title>Disk Management Guide</title>
  <topicref href="disk_management.dita"/>
  <topicref href="format_disk.dita"/>
  <topichead navtitle="Reference">
    <topicref href="disk_commands.dita"/>
  </topichead>
</map>

Generated navigation, e.g. a table of contents:

Content Reuse with Keys

A <keydef> in a map assigns a key to a resource. A keyref attribute, on elements such as <xref>, <image>, or <ph>, resolves that key from within a topic, so the target can change without editing every reference to it.

<map>
  <keydef keys="diskutil-guide" href="disk_management.dita"/>
</map>

No visible output—a keydef alone doesn’t appear in navigation, it only defines the key.

<p>For details, see <xref keyref="diskutil-guide"/>.</p>

For details, see Disk Management.

Keys can also carry reusable text, defined with <keywords> in the map and resolved with a keyref on <keyword> or <ph>:

<keydef keys="product-name">
  <topicmeta>
    <keywords>
      <keyword>Disk Utility Pro</keyword>
    </keywords>
  </topicmeta>
</keydef>

No visible output—defines the key’s text for use elsewhere.

<p>Welcome to <keyword keyref="product-name"/>.</p>

Welcome to Disk Utility Pro.

Content Reuse with Conref

A conref attribute pulls the content of an element with a matching id into another location, so the same content can appear in multiple topics without copying it.

Given this note, defined in the disk_management topic above:

<note id="disk_warning" type="warning">Formatting a disk erases all
  data on it.</note>
Warning: Formatting a disk erases all data on it.

Another topic can reuse it by reference:

<note conref="disk_management.dita#disk_management/disk_warning"/>
Warning: Formatting a disk erases all data on it.

conkeyref resolves the source through a key defined in a map, instead of a direct file path:

<note conkeyref="shared-notices/disk_warning"/>
Warning: Formatting a disk erases all data on it.