Home
Syntax and mark-up
Phrases
The semantics of words and phrases in DITA content is expressed through a broad range of phrase elements.
Marking up mark-up languages
The syntax phrase (synph) element can be used to describe elements and attributes in a mark-up language.

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.

Marking up mark-up languages

The syntax phrase (synph) element can be used to describe elements and attributes in a mark-up language.

When documenting XML mark-up languages, you should use the syntax phrase (synph) element to identify the names of language elements and attributes.

Do not use angular brackets to identify names of elements, or prefix attribute names with @. These formatting conventions should be added, if required, during the publishing process.

You should consider specialising synph into two separate elements, one to identify elements and one to identify attributes, to better semantically differentiate the two.

If you are including code snippets rather than describing the name of an element or attribute, use the code phrase (codeph) or code block (codeblock) element, and not the synph element.