(This post is part of the Learn DITA on Your Own series.)
Before you can start having fun with DITA, you need to install the following tools:
You use a DITA editor to write your topics, create your maps, and add your topics to maps. To generate your DITA content into the output format of your choice (PDF, .chm, HTML, etc.), you use the DITA Open Toolkit publishing engine, as shown in the following diagram:
An ideal DITA editor has the following features:
I’ve spent a few hours searching for a free XML editor that provides these features, but none seems available (and if I’m wrong, please, please let me know!). Many products provide a 30-day free trial, such as oXygen (which I use and love), and I’ll discuss this option when planning your DITA training.
For the World’s Smallest DITA Project, we will use Notepad++. It’s free, easy to use, and will work fine for what we want to do. Yes, when using Notepad++ you will be working with the tags, but as Sarah O’Keefe from Scriptorium said: “If you don’t understand the underlying DITA structure, you’re just going to continue to create badly structured information that is technically valid.”
Notepad++ is a very common editor, and you may already have it installed on your computer.
If you don’t, follow these instructions:
The DITA Open Toolkit (also called the DITA-OT) is an open source publishing tool that converts DITA content into various output formats such as PDF, XHTML, Eclipse Help, HTML Help, etc. To generate the output of a DITA map or topic, you run a command-line DITA-OT script that takes the map or topic as input and generates the content.
To download and install the DITA Open Toolkit:
The next step is to run the demo project provided with the DITA-OT to test your installation. To build the demo project, you run a script that asks for the DITA map that you want to build, the directory where you will store the output, and the type of output you want to create. For this test, we’ll accept the default answers to all questions.
ant -f build_demo.xml
The following message is displayed:
[echo] Please enter the filename for the DITA map that you [echo] want to build including the directory path (if any). [echo] The filename must have the .ditamap extension. [echo] Note that relative paths that climb (..) are not supported yet. [echo] To build the sample, press return without entering anything. [input] The DITA map filename: [C:\DITA-OT1.6.M5\samples\hierarchy.ditamap]
Note: If you get the following error message instead:
"java.exe"' is not recognized as an internal or external command...
You need to update your system PATH variable with the location of your Java bin directory (for example,
C:\Program Files\Java\jre7\) before you can try again. See these Java instructions for more information.
[echo] [echo] Please enter the name of the output directory or press return [echo] to accept the default. [input] The output directory (out): [out]
[echo] Please enter the type of output to generate. [echo] Options include: eclipse, tocjs, htmlhelp, javahelp, pdf, or web [echo] Use lowercase letters. [echo] [input] The output type: (eclipse, tocjs, htmlhelp, javahelp, pdf, [web], docbook)
[echo] Ready to build C:\DITA-OT1.6.M5\samples\hierarchy.ditamap [echo] for web in out [echo] [input] Continue? (Y, [y], N, n)
BUILD SUCCESSFUL Total time: 2 minutes 54 seconds
Note: If you do not get this message, see the DITA OT user documentation at the following location:
If you can’t make this work by following the documentation, please post your error in the comments section below and I’ll try to help you fix the issue.
If you want, you can run this procedure again, this time choosing a different output type.
You are now ready to write your first DITA document! This will be the subject of the next post. I will be off snowshoeing during the holidays and will come back with part 2 of the World’s Smallest DITA Project in 2014.
Until then…Happy Holidays, be safe, and be happy. :)