Home
Syntax and mark-up
Working with mark-up
Comments, draft-comment, and required-cleanup elements
Standard XML comment mark-up, and DITA specific draft-comment and required-cleanup elements, allow authors to leave notes, comments and unfinished edits that will not be included in the output when the document is published.

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 IDs
    Most DITA elements have an id attribute, which is used to uniquely identify the element when the element is re-used. In most cases, id attributes are optional, but an exception is the topic's root element, where it is mandatory.
  - Titles
    A title is not the same as a heading. A topic, a figure, a table and a section should each have only one title.
  - Hacks
    Avoid hacking: using mark-up workarounds that either break the DITA language rules or break the semantic integrity.
  - Comments, draft-comment, and required-cleanup elements
    Standard XML comment mark-up, and DITA specific draft-comment and required-cleanup elements, allow authors to leave notes, comments and unfinished edits that will not be included in the output when the document is published.
  - Use of class attribute
    The class attribute is used in specialisation, and should not be set by a DITA author. The class attribute should not be confused with the outputclass attribute.
  - Similar element names
    DITA includes semantic elements that have almost identical names to others, such as keyword and kwd. These similar elements are intended to be used in different authoring scenarios.
  - Controlling the look-and-feel of the output
    If an element with no specific semantic difference needs to be formatted differently in the output, you can apply the outputclass attribute to the appropriate element.
  - Attaching data to content
    Detailed metadata associated with a DITA element can be stored in data elements in the flow of the content.
- 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.
- 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.

Comments, draft-comment, and required-cleanup elements

Standard XML comment mark-up, and DITA specific draft-comment and required-cleanup elements, allow authors to leave notes, comments and unfinished edits that will not be included in the output when the document is published.

Standard XML comment mark-up can be incorporated in DITA documents, because DITA documents are, of course, XML documents. XML comments are delimited by a  suffix.

An example of an XML comment is:

<p>The kerb weight of the vehicle is 1395 kg.</p>
<!-- Check this is the correct kerb weight for XRW model -->

The draft-comment phrase element is a DITA-specific alternative to the XML comment, and has a similar purpose.

Use the draft-comment element or XML comment if you want to leave comments or notes for other authors. You should prefer the draft-comment element to XML comment, because it is possible to deliberately include draft-comment content in the output for document review and editing.

An example of a draft-comment is:

<p>The kerb weight of the vehicle is 1395 kg.
<draft-comment>Check this is the correct kerb weight for XRW model</draft-comment>
</p>

The required-cleanup block element is used during the migration of legacy (pre-DITA) content to DITA, to allow what would otherwise be invalid mark-up to be preserved during conversion. It is most commonly used by automatic conversion processes, such as the H2D HTML to DITA transformation provided in the DITA Open Toolkit.

The required-cleanup element can contain any well-formed mark-up.

Do not use the required-cleanup element for any purpose other than identifying invalid DITA mark-up that needs to be corrected.