Setting Up to Use the Generate Output Command

Details on setting up DITA-FMx to communicate with the DITA Open Toolkit.

The DITA-FMx > Generate Output command lets you generate output through the DITA Open Toolkit. This command provides two main options, you can generate output from the current topic or map file, or by using a specific Ant target. The setup required for these two options is described below.

DITA-FMx makes a call to the DITA Open Toolkit (DITA-OT) through a batch file named ~ant-build.cmd. This file is generated on the fly in the FrameMaker\DITA-FMx folder. In order for this batch file to work properly, the environment variables that define the location of Java and Ant (and possibly other utilities) must be properly defined. DITA-FMx provides an INI parameter (EnvironmentSetup) that lets you specify a batch file which loads in the proper environment settings. If you use this parameter and follow the instructions below, your OT connection should be fairly simple. However, if you use an older version of the OT or have special requirements you may need to ensure that the environment settings are defined globally.

If you are using DITA-OT 1.4.1 or later, we have found that you must use Java 1.5 or higher. We recommend that you use the “fullpackage” version of DITA-OT. Complete the following steps to ensure that you are able to generate output through the Open Toolkit (similar instructions apply if you’ve downloaded the OT version 1.4.2 or later):

  1. Download the "" file from SourceForge <>. Extract the contents of this file to your local file system into a directory named C:\DITA (or similar). It is important that the directory path that contains the DITA-OT directory has no spaces in any of the directory names. After extracting the contents of the OT archive, you will have a path such as C:\DITA\DITA-OT1.4.1.
  2. Download and install the Java Development Kit (JDK) version 5 or higher ( (Yes the DITA-OT install instructions say JDK1.4.2, but that won't work with OT 1.4 it appears. You must use version 5 or higher!
  3. Set your JAVA_HOME environment variable to the path to the newly installed JDK (perhaps "C:\Program Files\Java\jdk1.6.0_04").
  4. Copy the "ditafmx-ant.xml" file from the DITA-FMx folder to your DITA-OT folder.
  5. In the DITA-OT folder, copy the "startcmd.bat" file to "ditafmx-startcmd.bat"
  6. Open the "ditafmx-startcmd.bat" file in Notepad (or other text editor) and comment out the last line (add a "REM " in front of the line). If you don't comment out this line, it will still work, you'll just get an empty shell that hangs around each time you build. It should look like this:
    REM start "DITA-OT" cmd.exe
  7. Open the ditafmx-ini file in Notepad and locate the "EnvironmentSetup" parameter in the BuildFile section. This parameter should point to the "ditafmx-startcmd.bat" file. For example ..

    If you make use of the "Selected Target" option with the Generate Output command in Frame, you'll need to update this parameter in the associated "ANT:<targetname>" sections as well.

This should let you generate output through the default OT 1.4.1 targets, without requiring you to set up the system environment. If you use the PDF2 transform, you may need to do some additional work such as starting Frame from a shell in the OT directory (or adding a "cd %DITA_DIR%" line to the ditafmx-startcmd.bat file.

Alternatively, you may want to start FM from the DITA-OT directory. To do this just create a shortcut to FrameMaker.exe, and in the "Start In" field of the Shortcut tab, set this value to the path to your DITA-OT directory.

Generate Output: Current File Option

The Current File option of the Generate Output command lets you generate output from the current topic or map file using a pre-defined Ant script. The files referenced below are initially installed to the FrameMaker/DITA-FMx folder.

  1. Copy the ditafmx-ant.xml file to your DITA-OT directory.

  2. In the DITA-FMx > Options dialog, set the DITA-OT Directory field to reference the DITA-OT directory on your system.

That should be all that is required. The information about the current file and project are passed to the Ant script through command line parameters. By default, this provides three targets: HTML, CHM, and PDF. If you want to add others, modify the ditafmx-ant.xml file accordingly and add more targets to the BuildFile section of the ditafmx.ini file.

If you need to set up environment variables different from the default environment, the optional EnvironmentSetup parameter lets you specify a batch file to run before running the Ant script.

The ditafmx-ant.xml file contains a target for the FrameMaker Adapter. If you have this installed, you can enable access to it from the Generate Output dialog by adding a 4th item to the BuildFile section of the ditafmx.ini file “4=FMAdapter” and updating the Count parameter to 4.

In order to take advantage of ditaval filtering, you must register or create ditaval files so they are known to DITA-FMx. The Ditaval Manager provides the means to add existing files, or create new files.

Generate Output: Selected Target Option

The following steps should get you up and running with the Selected Target option of the Generate Output command.

  1. Copy the PROJECT.xml file to your DITA-OT directory and rename it something appropriate for your project.

  2. Edit the <project>.xml file and set the properties indicated in the comments so they match your system and project.

  3. Set up the ditafmx.ini file as follows:

    • Be sure that the LogFile parameter specifies a directory that exists before the Ant script is run, otherwise the build will fail.

    • The optional EnvironmentSetup parameter can be used to specify a batch file to run before running the Ant script in order to set up the environment.

    • In the examples below, swap “<PROJECT>” for the actual project name.

    • If the builds aren't working, try running the script from the command line: ant -f project.xml html

    1=<PROJECT> - CHM 
    2=<PROJECT> - HTML 
    3=<PROJECT> - PDF 
    [ANT:<PROJECT> - CHM] 
    [ANT:<PROJECT> - PDF]