Home
Syntax and mark-up
Lists
The purpose of a list is to make it easier for the reader to understand sequences of information and collections of like information. Different types of lists are used for different information structures.
Types of lists
There are four semantically-distinct general purpose list types in DITA, each of which is typically rendered differently in the output.

Introduction
Information types and topics
Topics are the building blocks of modular documents, and organising topics by semantic information types is one of the architectural features of DITA.
DITA map files
Syntax and mark-up
- Organisation of DITA elements
  Elements in DITA are grouped together into a number of categories for organisational and comprehension purposes.
- Working with mark-up
- Element domains
  Elements in DITA are arranged into domains for organisational purposes and technical reasons.
- Short descriptions
  The short description (or shortdesc) is arguably the most important component of a DITA topic, and is also one of the most difficult elements to write. Short descriptions should be written for every topic.
- Lists
  The purpose of a list is to make it easier for the reader to understand sequences of information and collections of like information. Different types of lists are used for different information structures.
  - Types of lists
    There are four semantically-distinct general purpose list types in DITA, each of which is typically rendered differently in the output.
  - Definition lists versus tables
    Definition lists should be used for structuring terms and their corresponding definitions, rather than an alternative table structure.
  - Lists within paragraphs
    Whether a list is contained within a paragraph, or whether it occurs as a separate parallel block after the paragraph, depends on the context. If the paragraph contains a lead-in to the list, then that list is bound to the paragraph, and the list should be a child of the paragraph.
  - Controlling number (enumeration) type
    The style of numbers and symbols used in lists is applied by the publishing tool during processing. To use different number types, you must change the processing templates or routines.
  - Listing user interface buttons
    Definition lists can contain images, and are therefore useful for explaining the meaning of buttons and graphics.
  - Parameter lists
    When documenting programming functions and interfaces, the parameter list can be used to explain parameters passed between applications and functions.
  - Choice lists
    When writing task topics, the choice list structure can be used to describe alternative step choices.
- Paragraphs
  Paragraphs are the basic components of topics. A paragraph (p) element should be a self-contained unit dealing with one idea or point, typically expressed in two or more related sentences. The p element should be used when no other semantically-specific block element is available.
- Procedures and steps
  The purpose of procedural documents is to explain to the reader how to accomplish tasks. The task information type is specifically designed for procedures, with a well-defined structure built around steps.
- Tables
  The purpose of a table is to structure, organise and present factual data that a user will need to look up or reference. There are two general purpose table types in DITA: table and simpletable.
- Phrases
  The semantics of words and phrases in DITA content is expressed through a broad range of phrase elements.
- Special characters and dates
Language and punctuation
Graphics and figures
Cross-referencing
Cross-references are a means of binding individual topics into a coherent and navigable document.
Content re-use
Metadata, conditional processing, and indexing
The DITA documentation process
DITA authoring concepts
Moving from style-based authoring to a structured authoring methodology such as DITA requires a radically different approach to writing.

Types of lists

There are four semantically-distinct general purpose list types in DITA, each of which is typically rendered differently in the output.

The four list types in base DITA are:

Simple Lists: A simple list (sl) is one where the items in the list are short phrases, and where the order of items in the list is not important. The list is usually rendered with each item on a separate line, without bullets or numbers.
Bulleted (unordered) Lists: An unordered list (ul) is one where the order of items in the list is not important. The list is usually rendered with bullets against each list item. The items are typically blocks of text.
Numbered (ordered) Lists: An ordered list (ol) is one where the order of items is critical to the meaning. The list is usually rendered with sequential numbers against the list items.
Definition Lists: A definition list (dl) is one comprising a set of terms and corresponding definitions. The list is usually rendered with definitions indented from the term and on the next line, or with definitions indented from the term on the same line as the term.

These lists are semantically distinct, although the difference between a simple list and an unordered list is minor. Some processors may output simple lists as inline lists, rather than block lists (separate lines per item).

List types are not interchangeable; the content of the list will determine which list type is appropriate for it. Choose a list type by considering the nature of the list, not by the way you think the list will be rendered in the output.

Screen captures showing the typical rendering difference between simple and unordered lists in PDF output — Figure 1. The difference between simple and unordered lists

Screen captures showing the difference between unordered and definition lists in PDF output — Figure 2. The difference between definition and unordered lists

Although simple lists are technically valid inside ordered, unordered and definition list items, you should avoid nesting simple lists inside other lists.

DITA includes some other special purpose list structures, such as parameter list (parml) and choice list (choices).