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 🍻🍻
0 Comments