Chapter 1. Installing XMLmind DITA Converter

Before you begin

XMLmind DITA Converter (ditac for short) requires the Oracle or Apple Java™ runtime 1.6 or above (but not newest Java 9, which has not yet been tested).
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
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_2_1.zip
    C:\ditac> dir ditac-3_2_1
    ... <DIR> bin
    ... <DIR> doc
    ... <DIR> docsrc
    ...
    XMLmind DITA Converter is intended to be used directly from the ditac-3_2_1/ 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_2_1\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.
      WARNING
      WARNING
      Please install and use either Apache FOP 1.1 or FOP 2.1+ Opens in new window. Please do not install and use Apache FOP 2.0 Opens in new window as we have found this version to have a severe bug (FOP-2461 Opens in new window).
      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).
    • If you want to generate Java Help, download and install Java Help Opens in new window (contains jhindexer and jhindexer.bat).
  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 XP, Vista, 7, 8, 10.
        Example: C:\Documents and Settings\john\Application Data\XMLmind\ditac\ on Windows XP. C:\Users\john\AppData\Roaming\XMLmind\ditac\ on Windows Vista, 7, 8, 10.
    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.2\fop\fop.bat
      
      -xfc E:\opt\xfc_eval_java-5_4_5\bin\fo2rtf.bat
      
      -jhindexer E:\opt\javahelp\javahelp\bin\jhindexer.bat
      
      -hhc "C:\Program Files\HTML Help Workshop\hhc.exe"

Child topics:

1. Contents of the installation directory

bin/ditac, ditac.bat
Scripts used to run XMLmind DITA Converter (ditac for short). Use ditac on any Unix system. Use ditac.bat on Windows.
doc/index.html
Contains the documentation of ditac. XMLmind DITA Converter Manual is available in all the output formats supported by ditac. You'll also find there the reference manual of the API of ditac (generated by javadoc).
docsrc/manual/
Contains the DITA source of XMLmind DITA Converter Manual.
LEGAL/, LEGAL.txt
Contains legal information about ditac and about third-party components used in ditac.
lib/
All the (non-system) Java™ class libraries needed to run ditac:
ditac.jar
contains the code of XMLmind DITA Converter.
resolver.jar
is Apache XML Commons Resolver Opens in new window which implements catalog-based entity and URI resolution.
relaxng.jar
is Jing Opens in new window version 20030619, James Clark's RELAX NG validator, slightly modified for use in XMLmind XML Editor Opens in new window and XMLmind DITA Converter. The details of the modifications are found in LEGAL/relaxng.README.
saxon9.jar
is Michael Kay's XSLT 2.0 engine. See http://www.saxonica.com/ Opens in new window.
whcmin.jar
snowball.jar
contains the code needed to run XMLmind Web Help Compiler Opens in new window.
xslthl.jar
contains the code of the XSLT syntax highlighting Opens in new window open source software component.
plus/
This directory is present only in the case of the ditac-N_N_N-plus-fop.zip distribution. It contains most recent Apache FOP Opens in new window (including hyphenation and MathML support). This XSL-FO processor is automatically declared and thus, ready to be used to generate PDF or PostScript.
schema/
Contains the DTD, RELAX NG and W3C XML schemas of DITA 1.3 1.2, 1.1, 1.0.1. File schema/catalog.xml contains an XML catalog which points to these local copies.
src/
Contains the Java source code of ditac. src/build.xml is an ant Opens in new window build file which allows to rebuild lib/ditac.jar.
whc_template/
Contains the template directory of XMLmind Web Help Compiler Opens in new window.
xsl/
Contains the XSLT 2.0 Opens in new window stylesheets used to convert DITA documents to a variety of formats.
fo/fo.xsl
Used to generate an intermediate XSL-FO file. After that, the XSL-FO file is converted to PDF , PostScript , RTF , WordprocessingML , Office Open XML (.docx) or OpenOffice/LibreOffice (.odt) by the means of an XSL-FO processor.
xhtml/xhtml.xsl
Used to generate XHTML 1.0 pages.
xhtml/xhtml1_1.xsl
Used to generate XHTML 1.1 pages.
xhtml/html.xsl
Used to generate HTML 4.01 pages.
xhtml/xhtml5.xsl
Used to generate XHTML 5 pages.
webhelp/webhelp.xsl
Used to generate Web Help containing XHTML 1 pages, which are then compiled using XMLmind Web Help Compiler Opens in new window.
webhelp/webhelp5.xsl
Used to generate Web Help containing XHTML 5 pages, which are then compiled using XMLmind Web Help Compiler Opens in new window.
htmlhelp/htmlhelp.xsl
Used to generate HTML Help files, which are then compiled using hhc.exe.
eclipsehelp/eclipsehelp.xsl
Used to generate Eclipse Help files.
javahelp/javahelp.xsl
Used to generate Java™ Help files, which are then archived in a .jar file.
epub/epub.xsl
Used to generate EPUB 2 files, which are then archived in a .epub file (Zip archive having a .epub extension).
epub/epub3.xsl
Used to generate EPUB 3 files, which are then archived in a .epub file (Zip archive having a .epub extension).