Setting Up to Use the Generate Output Command
Details on setting up DITA-FMx to communicate with the DITA Open Toolkit.
The
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 the DITA-OT Environment Setup File option (in DITA Options, External Applications dialog) which lets you specify a batch file that loads the proper environment settings when the OT is run. 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 the DITA-OT. Note that it is fine to use the latest version of the DITA-OT (which supports DITA 1.2) even though you’re using DITA-FMx 1.1 (which supports DITA 1.1).
Complete the following steps to ensure that you are able to generate output through the Open Toolkit:
- Download the latest “full” ZIP of the DITA-OT (for example DITA-OT1.5.4_full_easy_install_bin.zip) from SourceForge <sourceforge.net/projects/dita-ot/files/DITA-OT Stable Release/>. 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.5.4.
- Download and install the Java Development Kit (JDK) version 5 or higher (www.oracle.com/technetwork/java/javase/downloads). (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!
- Set your JAVA_HOME environment variable to the path of the newly installed JDK (perhaps "C:\Program Files\Java\jdk1.6.0_04").
- Copy the FrameMaker\DITA-FMx folder to your DITA-OT folder. file from the
- In the DITA-OT folder, copy the startcmd.bat file to ditafmx-startcmd.bat (in the same folder copy the file to a new name).
- 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
- In the DITA Options dialog, select the External
Apps button to display the External Application
Settings dialog. Set the value of the DITA-OT
Directory option to reference the main DITA-OT directory.
Then set the value of the DITA-OT Environment Setup File option
to reference the ditafmx-startcmd.bat file.
If you make use of the Selected Target option with the Generate Output command in Frame, by default this environment setup file is used for those builds as well. If you want to specify an alternate environment setup file, you can add the “EnvironmentSetup” parameter to the associated "ANT:<targetname>" sections.
This should let you generate output through the default OT 1.5.4 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.