DITA - Structured Documentation with XML

06/11/2023, Sun

Categories: #documentation

DITA Setup

DITA stands for Darwin Information Typing Architecture, it is an XML specification that prescribes tags for organizing your documentation content. For Dita to be able to generate a well-defined structure, it suggests a rather prescriptive methods of tag use. The intention of Dita is to promote content reuse so that your documentation project will be more manageable as it scales up in size and complexity.

Getting started with Dita begins with having these prerequisites.

Java
Text editor
DITA-OT

Alternatively, there are xml editors out there that bundle Dita together with Dita which offers you the convenience of an integrated DITA authoring experience. These editors tend to be in the family of WYSIWYG editors. Most of these solutions are paid software, but XMLmind XML Editor is a free alternative.

However, the rest of this article will focus on using more developer centric tools for better learning when working with the raw xml markup.

Installing Prerequisites

Java

The version of Java that DITA-OT version 4.0.2 supports is version 17. To make managing the versions of Java easier, using a general tools installer version manager such as asdf. Asdf is commonly used to install different programming languages onto your machine.

After installing asdf with the official installation instructions, you are ready to use it to install Java.

Asdf requires that you add plugins to manage the many tools that out there for installation. You install a plugin for a particular tool that you would want to use.

Add the Java plugin for asdf.

asdf plugin add java

List all Java versions to find the latest version 17 of Java.

asdf list-all java

Install the Java version. Pick a version that is up-to-date, the version of Java shown below is shown for demonstration purposes.

asdf install java oracle-17.0.6

Set the installed Java version as global.

asdf global java oracle-17.0.6

Additional Java configuration information can be found from the asdf java plugin page.

DITA-OT

The DITA-OT binary will provide the actual DITA functionality. This will put dita into the command line for processing our DITA xml documents.

Download Dita from github located at https://github.com/dita-ot/dita-ot/releases. Extract the zip file into a location where you can reference the dita binary.

Put the DITA binary into your path by adding this line into your .bashrc file. Substitute with your location of the DITA folder.

export PATH=$PATH:/the/path/to/your/Dita/dita-ot-4.0.2/bin/

Text Editor

A text editor with xml highlighting support is recommended.

Basic Example

The following will be a minimal DITA example. Create a dita-example folder with the associated DITA files.

dita-example/
├── map.ditamap
└── concept.dita

The map.ditamap serves as the entry point file that DITA reads to determine references to topic type and other ditamap files. This file indicates which files will be build for the final output. These referencing files have the extension of .ditamap.

With DITA, the two file extension types you will frequently encounter will be .ditamap and .dita. The .dita file are for storing the topic information content.

The map.ditmap file uses a <topicref> tag to reference the concept.dita file.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map chunk="by-topic">
    <title>DITA Topic Map</title>
    <topicref keys="concepts" href="concept.dita" toc="yes" />
</map>

DITA's authoring strategy involves writing for "topics" which serve as discrete cohesive units of information. The three more commonly used topic types are the <concept>, <task>, and <reference>. The type of topic you use will be determined by what that pieces of information is intended to convey to the audience.

The <concept> explains the background information of the subject that you are trying to illustrate. It will provide the general purpose of the subject.

The <task> topic will list out the specific instructional steps that are carried out when attempting to perform a 'task'. This topic type is suited for use with something that is found in a cooking recipe or assembly instruction manual where mechanical steps are listed in a bulleted list.

The <reference> topic is used for providing supporting information. This can be complementary information for the <concept>.

As for our example, we will focus on using the <concept> topic. To define a <concept> document, these first two lines are needed. The first line declares that it is a xml file, while the second is to help DITA identify it as a concept document.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

Next, the <concept> tag is added along with the <title> and <shortdesc> tags. The <title> states the subject that will be discussed and the <shortdesc> offers a brief description of the topic.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="concept">
    <title>Painting a Wall</title>
    <shortdesc>Periodic painting of a wall will ensure that moisture does not damage the material underneath. It also ensures that you living environment is visually pleasant to look at.</shortdesc>
    ...
</concept>

Add the <conbody> below the <shortdesc> along with the <section> information to describe the topic in detail. You can add additional sections for further details.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="concept">
    <title>Painting a Wall</title>
    <shortdesc>Periodic painting of a wall will ensure that moisture does not damage the material underneath. It also ensures that you living environment is visually pleasant to look at.</shortdesc>
    <conbody>
      <section>
          <title>Clearing the Area for Painting</title>
          <p>Remove obstructing items from the wall that is painted. You will need room to manuever you painting equipment.</p>
      </section>
    </conbody>
</concept>

Run the DITA command to generate the output in html.

dita --input=map.ditamap --format=html5

The dita command will create an out folder with these files.

out/
├── commonltr.css
├── commonrtl.css
├── concept.html
└── index.html

The map.ditamap outputs to the index.html file and the concept.html. The css files are auto-generated to support styling the generated html. View the html files in your browser.

WH