Home
Syntax and mark-up
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.
Identifying programming code
The codeblock and codeph elements are used to identify code snippets.

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.
  - Keeping connected blocks together
    When a block element is logically subordinate to the one that precedes it, the subordinate block should be nested within the first block. In other words, subordinate blocks should be child nodes, not siblings, of the leading block.
  - Paragraphs (and other block elements) within tables
    Avoid using block elements within normal tables. Only when a table cell contains more than one idea, fact or point should child block elements be used. Do not use block elements in simple tables.
  - Paragraphs (and other block elements) within notes
    Avoid using block elements within notes. Only when a note is comprised of more than one idea or point should child block elements be used.
  - Paragraphs (and other block elements) within list items
    Avoid using block elements within list items. Only when a list item is comprised of more than one idea or point should child block elements be used.
  - Paragraphs in reference topics
    Paragraph (p) elements should not be used in reference topics, as reference topics are intended to contain facts, not ideas.
  - Poetry, dialogue and fragments of text
    The lines element is used for content where the line breaks are important to the meaning of the text.
  - Identifying programming code
    The codeblock and codeph elements are used to identify code snippets.
- 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.

Identifying programming code

The codeblock and codeph elements are used to identify code snippets.

Examples of programming, scripting, or mark-up language code are marked up using the code phrase (codeph) and code block (codeblock) elements. As the element names suggest, code phrase is used when the code sample occurs inline within a paragraph or other block element, while code block is used when the code is more than one line long, and is a block in its own right.

Code block elements can be nested inside a paragraph (or other block element).

If you have text that introduces the codeblock and more text that immediately explains the code, you can use a structure such as in the following example:

<p>
  If you display debugging information, such as in:
  <codeblock>
    debugText = app.name & app.ver
    debug.print("Value is " & debugText)
  </codeblock>
  you must launch the application in debugging mode.
</p>

Line breaks can be used inside codeblock elements.