Chapter 1. Installing XMLmind DITA Converter

Before you begin

XMLmind DITA Converter (ditac for short) requires using a Java™ 1.8+ runtime.
On Unix, make sure that the Java bin/ directory is referenced in the $PATH and, at the same time, check that the Java runtime in the $PATH has the right version:
$ java -version
openjdk version "21.0.2" 2024-01-16
OpenJDK Runtime Environment (build 21.0.2+13-58)
OpenJDK 64-Bit Server VM (build 21.0.2+13-58, mixed mode)
On Windows and on the Mac, this verification is in principle not needed as the java executable is automatically found in the $PATH when Java has been properly installed.

Procedure

  1. Unzip the distribution in any directory you want.
    C:\> mkdir ditac
    C:\> cd ditac
    C:\ditac> unzip ditac-3_15_0.zip
    C:\ditac> dir ditac-3_15_0
    ... <DIR> bin
    ... <DIR> doc
    ... <DIR> docsrc
    ...
    XMLmind DITA Converter is intended to be used directly from the ditac-3_15_0/ directory. That is, you can run the ditac command by simply executing (in a Command Prompt on windows, a terminal on Unix):
    C:\ditac> ditac-3_15_0\bin\ditac
  2. Depending the output formats you want to generate, you'll need to download and install third-party external tools.
    • If you want to generate PDF or PostScript®, download and install Apache FOP Opens in new window.
      Alternatively, you may prefer to purchase RenderX XEP Opens in new window or Antenna House Formatter Opens in new window. Note that RenderX XEP Personal Edition Opens in new window is free to use.
      Note
      Note
      If you have installed Apache FOP and your DITA document contain MathML Opens in new window, you'll want to also install the JEuclid FOP plug-in Opens in new window. This plug-in is needed to add MathML support to Apache FOP.
    • If you want to generate RTF (can be opened in Word 2000+), WordprocessingML (can be opened in Word 2003+), Office Open XML (.docx, can be opened in Word 2007+) or OpenOffice (.odt, can be opened in OpenOffice/LibreOffice 2+), then you need to purchase XMLmind XSL-FO Converter Professional Edition Opens in new window.
      You can give XMLmind XSL-FO Converter a try by downloading Evaluation Edition from XMLmind XSL-FO Converter web site Opens in new window. Do not be surprised because XMLmind XSL-FO Converter Evaluation Edition generates output containing random duplicate letters. Of course, this does not happen with Professional Edition!
    • If you want to generate HTML Help, download and install the HTML Help Workshop Opens in new window (contains hhc.exe).
  3. If you have installed any of the above external tools, you need now to instruct ditac where to find them. This can be done using the following command line options: -fop, -xep, -ahf, -xfc, -jhindexer, -hhc. However, it is much more convenient to specify these command-line options once for all in a ditac.options file.
    1. Create ditac.options, a plain text file encoded using the native encoding of the platform (e.g. Windows-1252 on a Western Windows PC), in the ditac user preferences directory.
      The ditac user preferences directory is:
      • $HOME/.ditac/ on Linux.
      • $HOME/Library/Application Support/XMLmind/ditac/ on the Mac.
      • %APPDATA%\XMLmind\ditac\ on Windows. Example: C:\Users\john\AppData\Roaming\XMLmind\ditac\.
    2. Add the equivalent of a command-line option for each external tool installed in the preceding step. Use one or more newline characters to separate the options. More information in The ditac.options file.
      -fop E:\opt\fop-2.9\fop\fop.bat
      
      -xfc E:\opt\xfc_eval_java-6_4_1\bin\fo2rtf.bat
      
      -hhc "C:\Program Files\HTML Help Workshop\hhc.exe"

Child topics: