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.

Topics

DITA content is written in topics. <topic> is the base topic type: a title, an optional short description, and a body made up of common elements like paragraphs, lists, and tables. Other topic types used throughout this page, like concept, task, and reference, are specializations of <topic>.

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

Disk Management

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

A disk must be partitioned before it can be formatted.

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:

Common Topic 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

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.

Profiling and Filtering

A DITAVAL file lets a publishing pipeline profile content: include, exclude, or flag it by attribute value, without editing the source. Content is marked with profiling attributes, such as audience, platform, or product.

<p>Back up important data before making changes to a disk.</p>
<p audience="novice">Use Disk Utility to format and manage disks.</p>
<p audience="expert">Use <cmdname>diskutil</cmdname> to format and
  manage disks from the command line.</p>

Back up important data before making changes to a disk.

Use Disk Utility to format and manage disks.

Use diskutil to format and manage disks from the command line.

A DITAVAL file can then exclude the novice content and keep the expert content. The unconditioned paragraph has no audience attribute, so it’s unaffected and appears either way:

<val>
  <prop att="audience" val="novice" action="exclude"/>
  <prop att="audience" val="expert" action="include"/>
</val>

Back up important data before making changes to a disk.

Use diskutil to format and manage disks from the command line.

Specialization

DITA topic types and elements can be specialized: derived into new types and elements that attach more specific semantic meaning and narrow what content is allowed, while still validating against the base vocabulary. <concept>, <task>, and <reference>, used throughout this page, are the built-in specializations of <topic>.

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> specializes <topic> for a goal-oriented procedure: a <taskbody> with an optional <context>, an ordered <steps> sequence, and an optional <result>. Each <step> has a command (<cmd>), an optional explanation (<info>), and an optional result (<stepresult>).

<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>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>
    <result>
      <p>The disk is ready to store files.</p>
    </result>
  </taskbody>
</task>

Formatting a Disk

Format a disk to prepare it for use.

About this task

Formatting erases all data on the disk.

Procedure

  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.

Results

The disk is ready to store files.

Reference

A <reference> specializes <topic> for lookup information: a <refbody> with an optional <refsyn> for syntax, plus <section> and <properties> for the reference content itself. <properties> lists name/value pairs, such as command options, each with an optional description.

<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>
    <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>
  </refbody>
</reference>

Disk Commands

Command-line utilities for managing disks.

diskutil <command> [device]

Commands

CommandDescription
listLists available disks.
OptionValueDescription
-vverbosePrints detailed output.