Lesson 4: Creating DITA Content
Creating a topic in a text editor
DITA files are XML, and XML is plain text. Therefore, you can create an XML file in any text editor.
A basic DITA topic needs an XML declaration, a DOCTYPE declaration, a topic, an id attribute on the topic, and a title. Here is a minimal valid topic:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="myfirsttopic">
<title>Hello world</title>
</topic>
The topic above is valid, but it doesn’t have any body content. To make a topic useful, you need something like this:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="myfirsttopic">
<title>Hello world</title>
<body>
<p>Here is a paragraph</p>
<ul>
<li>bulleted lists are nice</li>
<li>especially if you have at least two items</li>
</ul>
<note>And don't forget the notes.</note>
</body>
</topic>
Creating a topic in an XML editor
You can use an editor to create content. The course recommends oXygen, which is not open source and free. So I will further investigate a tool to use later. I might use VSCode for the time being.
Notes, cautions, and warnings
The <note> element lets you create notes, cautions, warnings, and other admonishments.
<note>
Most surface-feeding ducks are agile and will take to the air easily. Approach these ducks slowly.
</note>
The type attribute for the <note> element is used to indicate different kinds of notes. DITA defines a number of values for the type attribute (Fun fact: the Docusaurus framework also uses these note values.):
- note (the default)
- attention
- danger
- caution
- important
- tip
<note type="warning">
Do not feed bread to ducks. It is unhealthy.
</note>
Bulleted and numbered lists
The most common lists used in DITA are unordered (“bulleted”) lists (<ul>) and ordered (“numbered”) lists (<ol>).
Both ordered and unordered lists contain one or more list item (<li>) element. An example is like this:
<p>The life cycle of a duck is similar to that of most birds:</p>
<ol>
<li>Egg</li>
<li>Hatchling</li>
<li>Duckling</li>
<li>Juvenile</li>
<li>Adult</li>
</ol>
An ordered list is useful for showing things that have a sequence, however, if you need to describe a process, you might be better off using the <steps> element in a task topic.
You can also nest a list by starting a new <ul> or <ol> element inside an <li> element:
<p>Ducks have these features:</p>
<ul>
<li>Webbed feet for swimming.</li>
<li>Shorter legs than other waterfowl.</li>
<li>Distinctive bill.
<ul>
<li>Wide and flat for filter feeding.</li>
<li>Long and narrow for fishing (Mergansers)</li>
</ul>
</li>
</ul>
In addition to the unordered list, DITA also defines a simple list (<sl>) element, which you can use for lists that contain just a few words in each item. The item in a simple list uses the <sli> element:
<p>There are several types of ducks:</p>
<sl>
<sli>Tree ducks</sli>
<sli>Surface-feeding ducks</sli>
<sli>Bay ducks</sli>
<sli>Sea ducks</sli>
</sl>
Blocks versus inline elements
The distinction between block and inline elements are:
A block element is a paragraph-level element, such as
<p>tag,<li>, or<codeblock>. As a general rule, a block element is separated vertically on the page. That is, if you have two<p>tags in a row, they are separated into two lines after being rendered.An inline element is an element that provides for markup inside a paragraph, such as
<tm>(trademark),<i>(italics),<xref>(cross-reference), or<term>(term). Inline elements, by default, do not result in line breaks.
Inline elements are similar to character styles in word processing tools.
However, some inline elements, such as <fn> (footnote) and <indexterm> (index entry), are processed differently. For example, <indexterm> entries are processed to create a back-of-the-book index. The text content of <indexterm> does not generally appear at the location where the inline element occurs:
<p>An inline element<indexterm>inline element</indexterm> <i>does not</i> result in line breaks.</p>