Home
Syntax and mark-up
Phrases
The semantics of words and phrases in DITA content is expressed through a broad range of phrase elements.
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.

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.

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.

In style-based authoring, formatting conventions have been used to identify the parts of command syntax for computer software applications. In this context, a command is a string of text that a user types in order to run an application and pass arguments to the application.

The Microsoft Manual of Style for Technical Publications suggests a syntax of:

command in bold
a set of choices surrounded by { }
individual choices separated by |
variable names in italics
repeatable arguments indicated by ...
optional items surrounded by [ ] or [[ ]].

For example, a command syntax might be represented as ant [-f filename] [-logfile filename] [-verbose].

In DITA, the following semantic elements are used to identify the components of a command:

kwd: A literal keyword used in a command, utility or batch file
option: an option or switch that modifies a command
oper: An operator (such as *, + or =)
var: The name of a variable or argument
delim: A delimiter character used to identify the beginning or end of one part of the syntax
sep: A separator character such as a bracket that is used within syntax

The syntax mark-up should be contained as a whole within a syntax phrase (synph) or syntax block (synblk) element.

An example of a marked up command line might be:

<synph>
 <kwd>ant</kwd> <option>-f</option> <var>filename</var>
 <option>-logfile</option> <var>filename</var>
 <option>-verbose</option>
</synph>

A typical output of this code is:

ant -f filename -logfile filename -verbose

When the command syntax is being used within an instruction to a user (usually within a task topic), the syntax should instead be contained within a userinput element, without the individual components of the command semantically identified.