2. The most commonly used “block elements”

The most commonly used block elements are borrowed from HTML and as such, should be immediately familiar to the reader.

Paragraphs and lists

A paragraph is represented by the <p> Opens in new window element.
A preformatted paragraph is represented by the <pre> Opens in new window element.
An itemized list is represented by the <ul> Opens in new window element. As expected, it contains <li> Opens in new window list item elements.
An ordered list is represented by the <ol> Opens in new window element.
A variable list is represented by the <dl> Opens in new window element. Unlike HTML's <dl>, the <dt> Opens in new window (term being defined) and the <dd> Opens in new window (term definition) elements must be wrapped in a <dlentry> Opens in new window element.
Example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
<ul>
  <li>First item.
    <p>Continuation paragraph.</p>
  </li>

  <li>Second item. This item contains an ordered list.
    <ol>
      <li>First do this.</li>
      <li>Then do that.</li>
      <li>Finally do this.</li>
    </ol>
  </li>

  <li>Third item. This item contains a variable list.
    <dl>
      <dlentry>
        <dt>Term #1</dt>
        <dd>Definition of term #1.</dd>
      </dlentry>

      <dlentry>
        <dt>Term #2</dt>
        <dd>Definition of term #2.</dd>
      </dlentry>
    </dl>
  </li>
</ul>
The above example is rendered as follows:
  • First item.
    Continuation paragraph.
  • Second item. This item contains an ordered list.
    1. First do this.
    2. Then do that.
    3. Finally do this.
  • Third item. This item contains a variable list.
    Term #1
    Definition of term #1.
    Term #2
    Definition of term #2.

Sections

DITA has no <h1>, <h2>, <h3>, etc, heading elements. Instead it has the <section> Opens in new window element which generally always has a <title> Opens in new window child element. Note that <section> elements cannot nest. Example:
1
2
3
4
5
6
 
<section>
  <title>The customary “hello word” program in Tcl/Tk</title>

  <pre frame="all">button .hello -text "Hello, World!" -command { exit }
       pack .hello</pre>
</section>
The above example is rendered as follows:

The customary “hello word” program in Tcl/Tk

button .hello -text "Hello, World!" -command { exit }
pack .hello

Figures and examples

Of course, DITA has also figure, table and example elements.
The <example> Opens in new window element is just a specialized kind of <section>.
The <fig> Opens in new window element generally has a <title> and generally contains an <image> element.
Like <img>, its HTML counterpart, the <image> Opens in new window “inline element” may be contained in any “block element”. The graphics file to be displayed is specified using the <href> attribute. The <image> element also has @width, @height, @scale and @align attributes.
Example:
1
2
3
4
5
6
7
8
9
10
 
<example>
  <title>Converting a color image to black and white</title>

  <pre>$ convert -dither Floyd-Steinberg -monochrome photo.png bwphoto.gif</pre>

  <fig>
    <title>The photo converted to black and white</title>
    <image href="bwphoto.gif" align="center"/>
  </fig>
</example>
The above example is rendered as follows:

Converting a color image to black and white

$ convert -dither Floyd-Steinberg -monochrome photo.png bwphoto.gif
Figure 3-1. The photo converted to black and white
bwphoto.gif

Tables

DITA has two kinds of table element: <simpletable> Opens in new window which is specific to DITA, and <table> Opens in new window which is in fact a CALS Opens in new window table (also know as a DocBook table).
<Simpletable> example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
<simpletable relcolwidth="1* 2* 3*">
  <sthead>
    <stentry>A</stentry>
    <stentry>B</stentry>
    <stentry>C</stentry>
  </sthead>

  <strow>
    <stentry>A,1</stentry>
    <stentry>B,1</stentry>
    <stentry>C,1</stentry>
  </strow>

  <strow>
    <stentry>A,2</stentry>
    <stentry>B,2</stentry>
    <stentry>C,2</stentry>
  </strow>
</simpletable>
A <simpletable> element contains an optional <sthead> Opens in new window element, followed by one or more <strow> Opens in new window elements. Both row elements, <sthead> and <strow>, contain <stentry> Opens in new window cell elements. The @relcolwidth attribute may be used to specify the relative width of each column.
The above example is rendered as follows:
A B C
A,1 B,1 C,1
A,2 B,2 C,2
Same as above example but using a CALS <table> this time:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
 
<table>
  <title>Sample CALS table</title>

  <tgroup cols="3">
    <colspec colwidth="1*"/>
    <colspec colwidth="2*"/>
    <colspec colwidth="3*"/>

    <thead>
      <row>
        <entry align="center">A</entry>
        <entry align="center">B</entry>
        <entry align="center">C</entry>
      </row>
    </thead>

    <tbody>
      <row>
        <entry>A,1</entry>
        <entry>B,1</entry>
        <entry>C,1</entry>
      </row>

      <row>
        <entry>A,2</entry>
        <entry>B,2</entry>
        <entry>C,2</entry>
      </row>
    </tbody>
  </tgroup>
</table>
CALS tables are quite complex and explaining how they can be used is out of the scope of this tutorial. Our recommendation is to use CALS tables rather than <simpletable>s only when you want a cell to span more than one row and/or more than one column.
The above example is rendered as follows:

Table 3-1. Sample CALS table

A B C
A,1 B,1 C,1
A,2 B,2 C,2