DITA lesson 3: Tags, cheatsheet

---

11 April 2024

DITA tags are semantic. The name of the tag is a clue to what that tag contains. For example, it’s self-evident that the following tag (called draft-comment) is meant for holding review notes by an editor, SME, or writer.

<draft-comment>Where are these values defined?
    In config.xml or categories.xml?</draft-comment>

In the previous lesson, you learnt that not all tags can be used in all topic types. Hold that thought while you become familiar with some tags. Oftentimes, DITA gives you a choice of more than one tag. In such cases, choose a tag based on the meaning inherent in the content that you’re tagging.

DITA tagging != formatting

DITA taging is about the type of content (”This is a note.” “These sentences form a paragraph.” “This information belongs to a table.”) rather than the appearance of the content (”Underline this word.” “Italicise this phrase.” “Make this word look bold and strong.”)

DITA does contain formatting tags such as <b> and <i>, but orgs didn’t adopt DITA because of formatting. Orgs adopt DITA, inter alia, because they want content to be marked up uniformly by all writers. And, no writer can look at some content and go, “This information is italics”.

Lists

The tag to use depends on the kind of list you’re writing.

Unordered list

A list where the order of the items in not important and where each item is, typically, rendered with a bullet in the output. The tag for an unordered list is <ul>, which cannot hold any content of its own except for one or more <li> tags where each <li> tag hold a list item.

DITA codeSample textTagged sample textSimilar tags

<ul>
  <li> </li>
  <li> </li>
</ul>

A <ul> tag can be used in the <concept> and <reference> topic types. It can also be used in the <task> topic type but, for task topics, also look at the tags that are listed in Procedures.

Ordered list

A list where the order of the items matters. Each item is rendered with a number, incremented by 1. The tag for an ordered list is <ol>, which cannot hold any content of its own except for one or more <li> tags where each <li> tag hold a list item.

DITA codeSample textTagged sample textSimilar tags

<ol>
  <li> </li>
  <li> </li>
</ol>

A <ul> tag can be used in the <concept> and <reference> topic types. It can also be used in the <task> topic type but if you find yourself using an <ol> in a task topic, pause. And ask yourself if the semantics of the content need a tag that’s listed in Procedures.

Definition list

A list where each item contains two parts: a term and its definition. The parent tag for a definition list is <dl>, which cannot hold any content of its own except for one or more <dlentry> tags, where each <dlentry> tag holds a term (in a <dt>) and its definition (in a <dd>). One term (<dt>) can have more than one definition (<dd>), just like in a dictionary, a word entry can have more than one meaning.

DITA codeSample textTagged sample textSimilar tags

<dl>
  <dlentry>
    <dt> </dt>  <!-- for the term -->
    <dd> </dd>  <!-- for the definition -->
  </dlentry>
</dl>

A <dl> tag can be used in the <concept>, <reference>, and <task> topic types, but because it is for definition lists, which are in the nature of referential information, the best use of the <dl> tag is in the <reference> topic type.

To decide whether to use <dl> or <parml>, think of the nature of the content. If it’s a series of argument for a command, the content is more in the nature of a parameter list than a definition list.

More list tags

DITA has a few more tags for other kinds of lists, such as glossaries. You’ll see them when you see them.

Images

DITA has one tag for images; it’s called <image> and has the following syntax:

<image href="remington.jpg"></image>

In this example, the source of the image is a file called remington.jpg, which is specified through the href attribute.

The <image> tag can’t contain anything except two optional child tags:

• <alt>, for alternate text. Always a good writing practise to use this tag even though it’s optional.

• <longdescref>, for a reference to a file that contains a description of the image. The reference could be to a local file or to an external URL.

If you need the image to have a title, you put it inside a <fig> tag, like so:

<fig>
  <title>Tools of the Trade</title>
  <image href="remington.jpg">
    <alt>A picture of a Remington typewriter</alt>
    <longdescref href="https://www.britannica.com/technology/Remington"
              format="html"
              scope="external"/>
  </image>
</fig>

DITA being XML, it’s also entirely possible to write your images as code, by using the <svg-container> tag to define a scalable vector graphic (SVG). This course doesn’t cover DITA SVGs.

What about videos?

DITA has an <object> tag that’s similar to the HTML <object> tag. Put your videos in <object>.

Tables

Just like there’s more than one tag for lists, similarly, there’s more than one DITA tag for tables too. Here’s a comparison table of some of the table tags that can be used in concept, task, and reference topics.

<table>

<simpletable>

<choicetable>

Header row

Yes

Yes

Yes

Header column

Yes

Yes

Yes

Merge cells

Yes

No

No

Title

Yes

No

No

Where used

<concept>, <task>, <reference>

<concept>, <task>, <reference>

<task>

The <table> tag supports more accessibility features than the other two.

Procedures

The most commonly used tag is <steps>, which cannot hold anything other than one or more <step> tags.

The <step> tag can’t hold anything in it either except for a single <cmd> tag. cmd is short for command. I believe the tag was named cmd because every sentence in a step is an imperative statement. Do this; do that.

DITA codeSample textTagged sample textSimilar tags

<steps>
  <step><cmd> </cmd></step>
  <step><cmd> </cmd></step>
</steps>

Links

For cross-references, through the <link> tag and its attributes:

The href attribute

For the link destination, which can be a DITA file, a location within a file, or a URL.

The scope attribute

For the degree of separation between the source and the target. Allowed values are local, peer, external, and -dita-use-conref-target.

Links can have several more attributes. You’ll see them by and by.

Code

For inline code, there’s <codeph>; for code that spans more than one line, there’s <codeblock>.

codephcodeblock

DITA code:

<p>Run the following command from the terminal: <codeph>curl -d "@apitest.json" -X POST http://127.0.0.1:8000/data</codeph>.<p>

Sample output:

Run the following command from the terminal: curl -d "@apitest.json" -X POST http://127.0.0.1:8000/data.

Sundry

The following tags are also often encountered in techdocs.

<shortdesc>

One single paragraph that contains a description of the contents of the topic.

<section>

A logical unit to group (or, organise) content. Very roughly analogous to the div tag in HTML.

<note>

A comment, explanation, cautionary advice, or warning.

<p>

A paragraph.

Summary

For a complete list, take a look at the DITA language specification. Again, remember that you don’t need to memorise these tags; just be aware, broadly, of what’s available and where they can be used. In the next lesson, you’ll learn to write some topics with these tags.

---

Lessons in this course

1. Information typing

2. Tags, introduction

3. Tags, cheatsheet

4. Topics

5. Maps

6. Topics, linking

7. Topics, more ways to link

8. Reuse

9. Profiling

---