Home
Syntax and mark-up
Phrases
The semantics of words and phrases in DITA content is expressed through a broad range of phrase elements.
Messages displayed in a user interface
DITA has four elements for marking up system messages, error messages, and other output from a computer system, or equipment user interface.

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.
- 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.
  - Program, script and routine names
    Program, routine, API and script names are identified using the cmdname and apiname elements.
  - Parameter and variable names
    DITA has four elements for distinguishing parameters, arguments and variables, depending on the context in which they are specified.
  - Messages displayed in a user interface
    DITA has four elements for marking up system messages, error messages, and other output from a computer system, or equipment user interface.
  - Printouts, read-outs and other system output
    When a computer system, application or hardware equipment produces some output intended for reading by a user, the output is described in DITA using the systemoutput element.
  - Trademarks and service marks
    The trademark (tm) element is used to identify different types of trade and service marks, and to record the mark owner. While there is no direct provision for a trademark image, a workaround can be used for this purpose.
  - Keyboard keystrokes
    The uicontrol element should be used when describing keys on a keyboard, and the userinput element for describing a series of keystrokes that the user must input. The name of the key should not be encapsulated or bracketed.
  - Footnotes
    The footnote (fn) element is used to nominate supplementary information that is not appropriate to be included in the flow of the content.
  - The coderef element
    The coderef element is used to reference external files, such as code samples, that are then imported as part of the processing to be rendered as standard text. The coderef is an alternative to the codeblock element for cases when the code is stored or maintained in its original form outside the DITA source.
  - The text element
  - Product, company names, and other keywords
    Product names, company names, and other special names are identified using the keyword element.
  - Complex command reference content
    When documenting complex software command references, you can use a combination of DITA phrase elements to describe the syntax. The mark-up can be converted to syntax formatting conventions during the publishing process.
  - Marking up mark-up languages
    The syntax phrase (synph) element can be used to describe elements and attributes in a mark-up language.
  - Phrases in different languages
    Words without a specific semantic meaning that are in a different language to the remainder of the topic can be identified by setting the containing element's xml:lang attribute to the international standard code for that language.
- 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.

Messages displayed in a user interface

DITA has four elements for marking up system messages, error messages, and other output from a computer system, or equipment user interface.

Whether it is through a software application, a machine instrument panel, or a consumer electronic device display, information is commonly displayed to the user through some sort of user interface. In some cases the information takes the form of lights, gauges, and dials, in other cases the information is audible, and in other cases it is textual or graphical. When describing these messages from the equipment in DITA, a number of semantic elements are used.

The main message elements are:

msgph: A short textual message displayed on a screen, as a sound, or on a printout. This element is used when the message will be described or quoted within an existing paragraph or block element.
msgblock: A long, multi-line textual message displayed on a screen, as a sound, or on a printout. This element is used when the message will be described or quoted in its own block element (or paragraph).
msgnum: The identification number of a message, such as an error message, usually displayed on a screen or instrument panel, or on a printout.
systemoutput: The response from a system to user input of some kind. This element is part of the DITA software domain.

Error messages are usually made up of a msgnum element (the error code) and a msgph or msgblock element. Likewise, status messages are best described with msgph or msgblock. The result displayed on a calculator after a user has entered an equation is best described with a systemoutput element.

The distinction between a message and system output is that the message is something produced by the system or device as part of its function, while a system output is something that the system returns as a direct result of something that the user inputs. Another way of putting it is that the systemoutput is used in conjunction with userinput to describe a conversation between the user and the system.