My DITA quick reference
I have been using DITA (Darwin Information Typing Architecture) to write technical documentation since 2012. This is a quick reference document that I share with writers who are new to working in DITA.
Tip: You can view the source files for this document at https://codeberg.org/trike_homard/DITA_quick_ref
DITA files
DITA is an XML-based specification that defines different types of topics for presenting information, and what is allowed in those topic types.
DITA topic types
DITA includes the following specialized topics that represent different information types.
- Concept
- Use a concept when you want to explain the benefits of a new feature, or how it works.
- Glossary entry
- Use a glossary to define a single term.
- Reference
- Use a reference when you want to list hardware requirements or system specifications, provide the syntax for a command, or describe API endpoints.
- Task
- Use a task to provide the steps a user needs to follow to accomplish a goal.
- Troubleshooting
- Use troubleshooting topics to describe a problem, and the steps to take to fix that problem.
DITA maps
DITA files are gathered in .ditamap files to set the order in which they appear in the output, and to define links between topics. The following code is an example of a .ditamap file.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
<topicref href="sample_concept.dita" type="concept" format="dita" scope="local"/>
<topicref href="sample_glossary.dita" type="glossary" format="dita" scope="local"/>
<topicref href="sample_reference.dita" type="reference" format="dita" scope="local"/>
<topicref href="sample_task.dita" type="task" format="dita" scope="local"/>
<topicref href="sample_troubleshooting.dita" type="troubleshooting" format="dita" scope="local"/>
</map>DITAVAL files
You can define the values for conditional processing by using .ditaval files. The following code is an example of a ditaval file.
<val>
<prop action="include" att="platform" val="linux" />
<prop action="exclude" att="platform" val="mac" />
<prop action="exclude" att="platform" val="windows" />
</val>Content reuse
One of the most powerful features of DITA is that it allows you to reuse elements from one topic in other topics by using content references. This is ideal for product names, common steps in procedures, or any other content that you need to repeat. You can use a content reference to reuse any element that has an id attribute specified.
You can reuse content directly by using the conref attribute. You can reuse content indirectly by using the conkeyref attribute.
Examples of direct reuse with the conref attribute
Let's say you have a file called conref_sample_1.dita that contains the following content.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="conref_sample_1">
<title>Sample topic with two paragraphs</title>
<conbody>
<section>
<p id="conref_example1">This is a paragraph with the id attribute specified.</p>
<p id="conref_example2">This is another paragraph with the id attribute specified.</p>
</section>
</conbody>
</concept>To reuse the first paragraph from a.dita in conref_sample_2.dita, add the following content in conref_sample_2.dita.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="conref_sample_2">
<title>Sample topic with a conref</title>
<conbody>
<section>
<p conref="conref_sample_1.dita#conref_example1"/>
</section>
</conbody>
</concept>You can reuse multiple elements in a row by using the conrefend attribute with the conref attribute.
For example, to reuse both paragraphs from conref_sample_1.dita in conref_sample_3.dita, add the following content in conref_sample_3.dita.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="conref_sample_3">
<title>Sample topic with a conref</title>
<conbody>
<section>
<p conref="conref_sample_1.dita#conref_example1" conrefend="conref_sample_1.dita#conref_example2"/>
</section>
</conbody>
</concept>Example of indirect reuse with the conkeyref attribute
For example, let's say that you want to use a topic in two different places, but with metric units in one, and imperial units in the other. To do this, create two files: metric.dita and imperial.dita.
The metric.dita file contains the following code.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="metric">
<title>Turbo encabulator dimensions</title>
<conbody>
<section>
<p id="dimensions">The turbo encabulator is 5.08 cm tall, 45.72 cm wide, and 30.48 cm deep. It weighs 23 kg.</p>
</section>
</conbody>
</concept>The imperial.dita file contains the following code.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="imperial">
<title>Turbo encabulator dimensions</title>
<conbody>
<section>
<p id="dimensions">The turbo encabulator is 2 inches tall, 18 inches wide, and 12 inches deep. It weighs 50 lbs.</p>
</section>
</conbody>
</concept>To reuse this content in c.dita, add a <keydef> element to your map that points to either metric.dita or imperial.dita. In the following example the <keydef> element points to metric.dita.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
<keydef href="metric.dita" keys="units"/>
<topicref href="conkeyref_sample_1.dita" scope="local" format="dita"/>
</map>Add the following code in conkeyref_sample_1.dita.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="conkeyref_sample_1">
<title>Sample topic with a conkeyref</title>
<conbody>
<section>
<p conkeyref="units/dimensions"/>
</section>
</conbody>
</concept>Commonly-used DITA elements
Learn about commonly-used DITA elements.
Tip: The list of elements on this page is not exhaustive. For a full list of DITA elements, see Content models for technical content package in the DITA specification.
<alt>- A description of the image in an image element. Alt text is important for accessibility and is read by screenreader software.
<cause>- The cause of an issue described in a troubleshooting topic.
<choice>- One option that a user can choose to complete a step. Must be contained by a choices element.
<choices>- A list of choice elements for a step.
<cite>- The title of a book, article, or website.
<cmd>- The instruction to follow in a step.
<cmdname>- The name of a command.
<codeblock>- A block of code. This could be a multi-line program, or a single-line command for a user to run.
<codeph>- An inline bit of code.
<coderef>- A reference to an external file to be displayed in a codeblock.
<colspec>- Used to specify details about column, such as width and alignment, in the tgroup element of a table.
<conbody>- The body of a concept topic.
<context>- Information about a task.
<dd>- The definition of a term in a dlentry.
<desc>- A description of an image in a fig element.
<dl>- A definition list. Each term in the definiton list is contained in a dlentry.
<dlentry>- An entry in a dl.
<draft-comment>- A draft comment. Used for review and discussion about the content in a file. Draft comments are typically excluded from the output.
<dt>- The term being defined in a dlentry.
<entry>- An entry in a table row.
<example>- A section of a concept, reference, or task topic that is used to provide an example.
<fig>- A block element that contains an image. May also contain a title and a desc.
<filepath>- A file name, the path to a file, or both.
<glossdef>- The definition of a glossterm in a glossentry
<glossentry>- An entry in a glossary. Must contain an id attribute.
<glossterm>- A term in a glossentry
<image>- An image. Use the href attribute to call an image file. Use the width and height attributes to specify the dimensions of an image.
<info>- Information about a step or substep.
<keydef>- Used to define keys that are called in a map. Must include the keys attribute. Can also include an href attribute to call keys from a specific file.
<keyword>- A keyword, such as a product name.
<li>- A list item in a ol or ul.
<lines>- A block of text where the linebreaks are significant, but other whitespace is not.
<link>- A link to a related website in a related-links element. Can include a linktext element.
<linktext>- Text to be displayed for a link.
- A series of menu choices. Contains one or more uicontrol elements.
<msgblock>- A multiline message, such as an error message.
- A reference in a map to a topic or another map that is not included in the map itself, but will be accessible in the output.
- The
<navtitle>element is used to set how a topic title appears in the table of contents. You can set the<navtitle>within a topic, or in a map. <note>- Used for notes. Set the type attribute to specify the type of note, such as attention, caution, danger, important, notice, restriction, tip, or warning.
<ol>- An ordered list that contains li elements.
<p>- A paragraph of text.
<parml>- A list of parameters. Each parameter is contained in a plentry.
<parmname>- The name of a parameter.
<pd>- A parameter definition in a plentry element.
<ph>- A phrase. If the phrase is meant to be reused, it should have an id attribute specified. If the phrase is meant for conditional processing, it should have an attribute such as outputclass, platform, product, or rev specified.
<plentry>- An entry in a parml. Contains a pt element and a pd element.
<pre>- Preformatted text. Linebreaks and whitespace are preserved.
<prereq>- Prerequisites for a task.
<pt>- A parameter term to be defined in a plentry element.
<q>- Quoted text. Use this rather than inserting quotation marks manually.
<refbody>- The body of a reference topic.
- A list of link elements to related websites.
<relcell>- A table cell in a relrow. Contains one or more topicref elements. The topicref elements in a relcell are treated as being related to the topicref elements in other relcell elements in the relrow.
<relrow>- A row of relcell elements in a reltable.
<reltable>- A relationship table. Use this to specify related links to other topics.
<remedy>- The remedy to an issue in a troubleshooting topic.
<result>- Used in a task topic to describe the result of completing the task.
<row>- A row in a table. Contains one or more entry elements.
<screen>- A textual representation of a computer screen.
<section>- A section of a concept or reference topic.
<shortdesc>- A short description of a topic. The content of the shortdesc element appears as linktext and as the page description in search results.
<step>- A step in a task. Must be contained by a steps or steps-unordered element.
<stepresult>- The result of a step.
<steps>- An ordered list of step elements.
<steps-unordered>- An unordered list of step elements.
<steptroubleshooting>- Troubleshooting information for a step.
<stepxmp>- An example of a step.
<substep>- A substep of a step. Must be contained in a substeps element.
<substeps>- An ordered list of substep elements for a step.
<systemoutput>- The text that is output after running a command.
<table>- Use a table to present data in columns and rows. Use a tgroup element to define the columns, a thead elements to define the header row, and a tbody element to define the table body.
<taskbody>- The body of a task topic.
<tasktroubleshooting>- Troubleshooting information for a task.
<tbody>- Defines the body of a table. Contain one row element for each row.
<tgroup>- Defines the columns of a table. Contains one colspec element for each column.
<thead>- Defines the header row of a table.
<title>- The title of a DITA topic, a fig, a section, or a table.
<titlealts>- Defines alternative titles for a DITa topic, such as a navtitle.
<tm>- A trademarked term. You must set the type attribute to tm for a trademark, or reg for a registered trademark. Set the trademark attribute to the trademarked term itself.
<topichead>- A text-only entry in a table of contents. Specify the text in a navtitle element.
<topicmeta>- Defines metadata about a topichead element or a topicref element.
<topicref>- A reference to a topic in a ditamap or in a reltable.
<troublebody>- The body of a troubleshooting topic.
<troubleSolution>- A container for the cause and remedy in a troubleshooting topic.
<uicontrol>- An control in a user interface, such as a button, a field, or a menu item.
<ul>- An unordered list that contains li elements.
<userinput>- Text that a user should enter in a field, or in response to a prompt.
<varname>- A variable that a user must supply in a command.
<wintitle>- The title of a window in a user interface.
<xmlelement>- Used to mention XML elements in text.
<xref>- A cross reference to a topic or an element in a topic.