DITA lesson 2: Tags, introduction

---

9 April 2024

In the previous lesson, you learnt about arranging information into discrete buckets called topic types. In this lesson, you’ll learn how to move that information to the DITA vocabulary.

DITA is a markup language, which means that all content in DITA is marked up (or, labelled with) tags. Because DITA tags are almost always semantic, the name of the tag itself is a clue to its purpose and function.

For example, consider the following text: The Adventures of Tom Sawyer

This text can be marked up with a tag called <title> in the following manner:

<title>The Adventures of Tom Sawyer</title>

DITA has a finite set of tags, and has strict rules about which tags can be used where. Every topic type has its own set of tags. Some tags can be used in all topic types; some can’t and are specific to only certain topic types. For example, the tag called <steps> can be used only in a <task> topic type, while the tag called <section> can be used in both <concept> and <reference> topic types, but not in the <task> topic type.

Every DITA topic must have the following two tags as an essential requirement:

• The tag for the topic type. These tags are eponymous: <concept>, <task>, and <reference>.

• A <title> tag that immediately follows the topic-type tag.

Therefore, all the following three examples are valid DITA files.

ConceptTaskReference

<concept id = "some_ID">

<title>The adventures</title>

</concept>

However, you and I live in the real world. Most of the time. In the real world, all DITA authoring tools will almost always insert (automatically, without being asked) a body tag after that first essential <title> tag.

Therefore, in the usual tech-writer life, a minimally valid DITA topic looks like this:

ConceptTaskReference

<concept id = "some_ID">

<title>The adventures</title>

<conbody>
...
Why do I exist?
...
</conbody>

</concept>

You don’t have to memorise either the tag names or the places where they can be used. DITA is an authoring system that’s used by very large enterprises, which will always make available some kind of XML authoring tool to its writers. All of these DITA authoring tools have in-built validations that make it impossible very difficult for you to mark up content with an invalid tag. The important thing for a writer is to decide which topic type to use, and then to take the help of the authoring tool to insert tags as needed.

For the curious, however, here’s an indicative list of tags that these topic types can contain. It’s not a complete list.

ConceptTaskReference

<concept> *
        <title>  </title> *
        <titlealts>  </titealts>
        <shortdesc>  </shortdesc>
        <conbody>
                <dl> | <parml> | <div> | <fig> |
                <syntaxdiagram> | <imagemap> | <image> |
                <note> | <ol> | <p> | <pre> | <codeblock> |
                <msgblock> | <screen> | <simpletable> |
                <sl> | <table> | <ul> | <section> |
        </conbody>
        <related-links>  </related-links>
</concept> *

Every tag has a name, for example, shortdesc or title.

Some tags can contain child tags and sometimes, the parent tag can hold content independently (along with child tags and their content) but sometimes, the only thing that a parent tag can hold is child tags. Here’s an example for each of these two cases.

Parent tag can hold content by itselfParent tag can’t

<note>The value in the <varname>outputdir</varname> field
should include the complete file path.</note>

In this example, the <note> tag contains some text and also contains another tag called <varname>.

Further, every tag also has several attributes that describe the tag. You can think of attributes as tag-metadata; they contain information about, and for, the tag.

ID required for topic type

Every topic-type tag must always have an id attribute.

So, <concept></concept> will always fail a validation check; <concept id="_some_value_"></concept> will pass.

A tag can have more than one attribute. Every attribute has a name and a value. Here’s an example of a link tag that has an attribute named href (with the value being pqr.dita) and an attribute named scope (whose value is local).

<link scope="local" href="pqr.dita">

In the next lesson, you’ll learn about a few DITA tags that are often used for marking up lists, tables, images, steps, and such other things that are used by technical writers.

Recap

• Every topic type has a finite set of tags that can be used in a very specific order.

• Only one tag is an essential tag in every topic type. This tag is the <title> tag that immediately follows the tag for the topic type.

• Some tags are exclusive to certain topic types; some tags can be used in more than one topic type.

• Tags can contain other tags but this is unidirectional; no parent tag can ever be contained by any tag that can become its child tag.

• Tags can have one or more attributes, where each attribute is like a key-value pair.

---

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

---