Most used DITA XML tags in software technical writing

DITA is used in all forms of technical writing. It is essential for a writer to know about the functions of the tags that help to create markup in the document.

As a writer, it is not possible to know and remember each of the tags. However, there are some most used tags that you should get a hang of it. Using those judicially creates a good quality document with proper formatting.

It is not possible to list all the tags but, in this article, we have created a comprehensive list of DITA XML elements or XML tags.

  

What are DITA XML Elements?

A DITA XML element is an XML tag. It has a start tag and an end tag of the same name.

 

What are the different Types of DITA XML elements?

DITA classifies elements into Block and Inline elements.

• Block elements – This element starts a new line.
• Inline Elements- This element is appended in the same line.

Block elements list

Use block elements to distinguish text based on the type of text that it is.

Element	When to use
<abbreviated-form>	When glossary terms exist in the document tree, the abbreviated form element references a glossary term in a topic.
<abstract>	Use this element immediately after <map><tittle> to insert multiple <shortdec>. This is useful when the short description is slightly different for different products and you want to use profiles to exclude a short description from a publication.
<codeblock>	Use to describe or show sample lines of programming code.
<dl>	Definition list: HTML output only. Not well supported in PDF. Use to describe a term with the associated definition.
<draft-comment>	Use to insert comments that you want to keep in the XML.
<example>	Use to describe or illustrate an example that supports the current topic.
<fig>	Use to insert an image that requires a caption title. This is used only when the topic title is not sufficient to make it clear what the illustration represents or when there is more than one illustration needed in the same topic and each illustration requires a title to distinguish it.
<image>	Use to insert an image that does not require a caption title.
<lines>	Use for authoring an address where each line of the address must be on a separate line without the usual paragraph spacing as with the <p> element.
<lq>	A long quote indicates content quoted from another source. Use the quote element <q> for short, inline quotations, and long quote <lq> for quotations that are too long for inline use.
<msgblock>	Use to describe a multi-line message or set of messages. The message block can contain multiple message numbers and message descriptions, each enclosed in a <msgnum> and <msgph> element. It can also contain the message content directly.
<note>	Use for authoring important notes that must be set apart from the paragraph text to emphasise something important.
<ol>	Use for authoring an ordered list. Limit lists to two levels deep.
<p>	Use for paragraph text. When the text in a paragraph act as lead-in text, the paragraph can contain an ordered or unordered list.
<required-cleanup>	Use to label content that requires cleanup. This element should not remain in the XML. The intent is to remove all required cleanup elements before publication.
<screen>	Use to illustrate sample DOS or terminal text.
<section>	Use as a container for a block of text that requires a title to set apart the content block.
<systemoutput>	Use to document a system message text.
<table>	CALS or Simple table for all table formats.
<ul>	Use for authoring an unordered list. Limit lists to two levels deep.
<xref>	Use for referencing related information only when the reference always must be present with the topic for all uses.

 

Inline element list

Use inline (phrase) elements to distinguish text based on the type of text that it is. The style sheets may apply special processing on some inline elements, so use the correct semantic element that represents the text the element surrounds.

 

Element	When or How to Use
<apiname>	Use to distinguish the name of an API.
<b>	Use the make bold.
<i>	Use to make Italics.
<u>	Use to make underline.
<cite>	Use to distinguish an external book or document name.
<cmdname> (command name)	Use to distinguish a DOS or terminal command.
<codeph> (code phrase)	Use to distinguish a code phrase.
<data>	Use to store a text string.
<draft-comment>	Use to insert comments that you want to keep in the XML to communicate information about something to reviewers or to other authors.  You can then choose to display or not display draft-comment text in output based on your style sheet configuration.
<filepath>	Use to distinguish a directory path, file name, or URL address.
<fn>	Use in body text or table text to annotate text with a number call-out. Footnote text appears at page bottom in HTML and PDF outputs.
<keyword>	Apply the @keyref attribute to call a key definition.
<lines>	Used in addresses to keep the single spacing between the address lines.
<lq> (long quote)	Use to distinguish content quoted from another source. The text stands apart from other paragraph text.
<menucascade>	Use to describe menu actions or Windows Start actions.
<msgph>	Use to distinguish a system message.
<parmname>	Use to distinguish the name of an application programming interface parameter within the text the flow of your topic.
<ph> (phrase)	Use to call a key definition using the keyref attribute.
<pre>	Use in a table the cell where the text is a code sample that must maintain spaces and carriage returns.
<q> (quote)	Use to distinguish content quoted from another source. The text remains inline the sentence text.
<shortcut>	Use to describe a short cut keystroke combination inside a <uicontrol>
<term>	Use to distinguish new terminology.
<tutorialinfo>	Use for additional information that is useful when the task is part of a tutorial.
<uicontrol> (user interface control)	Use to mark-up names of buttons, entry fields, menu items, or other objects that allow the user to control the interface.
<varname>	Use to distinguish a variable name in file paths or code samples.
<wintitle> (window title)	Use to distinguish a window or dialogue box name.

Conclusion

Knowledge of the DITA XML elements are very much essential to create a well-marked up document. In this article, we have produced a comprehensive but not exhaustive list of DITA XML elements/Tags.

If you like reading this article and found it useful, please share the article so that it reaches to most of the technical writers.

Thanks for reading.

Cheers 🍻🍻