Home
Syntax and mark-up
Phrases
The semantics of words and phrases in DITA content is expressed through a broad range of phrase elements.
The text element

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.

The text element

The text element, introduced in DITA 1.2, identifies a snippet of plain text that has no other special meaning (or presentation requirement). It should only be used when no other semantic element is appropriate. The text element is almost identical to the ph element, but cannot contain nested semantic element in the way that ph can contain, for example, image elements.

At first look, there seems to be no reason for having an element to contain text that has no semantic meaning! However, there are special circumstances when the text element makes sense, and that's when some text needs to be distinguished from other text, and when no other elements are allowed. The most likely example of this is when some text needs to be transcluded with a conref into a place where other elements are not permitted.

Do not use text in a place where ph is valid.