Helpinator + DITA Tutorial

DITA (stands for Darwin Information Typing Architecture) is a mature xml-based documentation authoring standard. You can read more about it on Wikipedia: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture and it’s website: http://docs.oasis-open.org/dita/v1.2/os/spec/DITA1.2-spec.html

Helpinator allows to create DITA project from your project content with a single mouse click. This allows to use Helpinator for writing new technical content in any documentation project that is already based on DITA.

In this tutorial we will follow the procedure step-by-step, from installing DITA Open Toolkit to compiling a sample PDF document from it.

1. Download and install DITA Open Toolkit (DITA-OT).

DITA itself is just an open standard of technical content markup based on XML. The standard is huge and versatile far beyond then needs of software documentation but still you need tools to produce documents from it that you can ship to end users. Most of them are not free, with some exceptions and one of them is DITA Open Toolkit (DITA-OT).

DITA-OT tools are written in Java, so you will need Java Development Kit (not just Java Runtime) to use it, so download and install it first if it is not on your machine yet.

Then go to the DITA-OT site and download DITA-OT package for Windows. At this moment the latest version is 3.3.3 and it is available for download via this link: https://github.com/dita-ot/dita-ot/releases/download/3.3.3/dita-ot-3.3.3.zip

Unpack it into a dedicated folder, say “C:\DITAOT“.

Now you have C:\DITAOT\bin folder that holds dita.bat batch file that actually does all the job. You can run to see a brief help on parameters that it takes.

2. Export DITA from your Helpinator project

Click “Batch Compile” on the main tool bar. “Batch compile” dialog appears.

“Batch Compile” icon on the main toolbar

Scroll the list on the left down to DITA output and double-click it to add to the project.

Set “Save to” to the folder where you want to store your DITA project to. Say, “C:\Project\help\dita“.

Helpinator Batch Compile – DITA

Click on lightning bolt icon. This will create all DITA project files in the specified directory.

3. Create output using DITA-OT.

Now we can proceed to generating desired user content. Let’s say we want to create a PDF file from our DITA project files. You can open command line and run dita.bat with required parameters OR you can use a GUI tool that we created for you, called “DITA Open Toolkit Launcher“. It is a GUI wrapper around dita.bat that allows to create batch projects using visual editor, store, run and re-run them with less effort. You can download it here: https://www.helpinator.com/downloads/ditaotlauncher.zip

Download and install DITA Open Toolkit Launcher, then run it. You can see the list of formats on the left, double-click “PDF” in it, it will add PDF output to the project. Below the project items list there are item properties where you can select source file and output folder paths. Source in our case is “C:\Project\help\dita\main.ditamap” (the main bookmap generated by Helpinator), set output folder to “C:\Project\Help\PDF\“.

DITA OT Launcher PDF params

Now click “Run” on the main tool bar. For the first time it will ask to select path where dita.bat file is. In our case it is “C:\DITAOT\bin\dita.bat“. Then the tool will launch dita.bat with required parameters and produce PDF file in the output folder.

DITA OT Launcher Options
DITA OT Launcher Log

Leave a comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.