Publishing with the DITA Open Toolkit

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

The Generate Output command lets you publish output through the DITA Open Toolkit. This command provides two main options: generate output from the current topic or map, 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 in the user’s DITA-FMx folder (use the Open DITA-FMx Folder command). 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.

The DITA-OT Directory and the DITA-OT Environment Setup File fields in the External Application Settings dialog must be specified to load the proper environment settings when the DITA-OT is run. Setup varies depending on the version of the DITA-OT. OT 1.x requires some additional setup, but OT 2.x and 3.x are quite simple.

Complete the following steps to enable publishing through the DITA-OT:

Download the latest ZIP of the DITA-OT <www.dita-ot.org/download>. Extract the contents of this file to your local file system into a directory named C:\DITA (or similar). It is a good practice to ensure that the path to 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-ot-3.5.4.
Make sure you’ve got a recent version of Java Development Kit. We recommend using OpenJDK from adoptopenjdk.net, but other compatible options are listed in the DITA-OT documentation (www.dita-ot.org).
Your JAVA_HOME environment variable should be set to the path of the JDK (perhaps "C:\Program Files\Java\jdk1.8.0_65"). This will typically be handled by the JDK installation program.
DITA-OT 1.x only:
1. Copy the ditafmx-ant.xml file from the Program Files\Adobe\FrameMaker\DITA-FMx-2 folder to your DITA-OT folder.
2. 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).
3. Open the ditafmx-startcmd.bat file in Notepad (or other text editor) and comment out the last line (add a “REM” at the start 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 bin\dita.bat file (for OT 2.x or later) or the ditafmx-startcmd.bat file (for OT 1.x).

Note:
For DITA-OT versions prior to 1.6 as well as versions 3.1.2 and 3.1.3, you’ll be prompted to enter the OT version. These versions do not expose a way for DITA-FMx to know the version number. This is required.

(OT 1.x only) If you make use of the Selected Target option with the Generate Output command, 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.

If you’re using DITA-OT 3.2 or later, the currently installed plugin targets will automatically be listed in the Current File list in the Generate Output dialog. This is done when the DynamicTargets option is enabled in the BuildFile section of the ditafmx.ini file (the default). If you’re using an older version of the DITA-OT or have this option disabled, you’ll need to make sure the list of targets in the BuildFile section includes the targets you plan to use.

(OT 1.x only) You may need to start Frame from a shell in the OT directory, or add 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 (OT 2.x or later)

The Current File option of the Generate Output command lets you generate output from the current topic or map. The information about the current file and selected target are passed to the build process through command line parameters.

Most of the information below is only useful if you’re not using the DynamicTargets option (described earlier). This provides for additional control over the publishing targets available in the Generate Output dialog.

By default DITA-FMx provides support for 8 publishing targets. To add or modify this list, edit the BuildFile section of the ditafmx.ini file. The following is the default BuildFile section after completing the basic setup (assuming OT 2.5.4):

[BuildFile] 
EnvironmentSetup=C:\DITA\dita-ot-2.5.4\bin\dita.bat 
DitaDir=C:\DITA\dita-ot-2.5.4\ 
AntCommand=ant 
AntScript=ditafmx-ant.xml 
Count=8 
1=xhtml 
2=html5 
3=pdf 
4=htmlhelp 
5=javahelp 
6=eclipsehelp 
7=tocjs 
8=troff

Note: The AntCommand and AntScript parameters are ignored when using the DITA-OT 2.x or later.

Each of the numbered entries corresponds to target (transformation type) defined in the OT. If you want to add additional targets, install the necessary OT plugin to support those targets, then add the corresponding target name to the BuildFile section (don’t forget to update the Count parameter).

As of DITA-FMx 2.0.07 three additional BuildFile parameters are available:

OT2Params: Pass additional parameters to the OT transformation.

Note: Specifying an output location (via '-output=' or '-o='), will override the creation of the default build directory based on the current filename.
OT2Params-<build>: Same as the OT2Params parameter, but only applies to the specified DITA-FMx build. If set, this value overrides the OT2Params value. For example, the parameter name could be: OT2Params-xhtml
OT2Logging: Possible values are: Verbose (the default value, if not specified), Debug, or None (errors only).

If you need to use a different DITA-OT installation for a specific build target, add new entries for EnvironmentSetup-<target> and DitaDir-<target>. For example, if the “chm” target required the use of a specially set up DITA-OT installation, you might use the following:

[BuildFile] 
EnvironmentSetup=C:\DITA\dita-ot-2.5.4\bin\dita.bat 
DitaDir=C:\DITA\dita-ot-2.5.4\ 
EnvironmentSetup-chm=C:\DITA\dita-ot-2.1.1-special\bin\dita.bat 
DitaDir-chm=C:\DITA\dita-ot-2.1.1-special\ 
AntCommand=ant 
AntScript=ditafmx-ant.xml 
Count=9 
1=xhtml 
2=html5 
3=pdf 
4=chm 
5=htmlhelp 
6=javahelp 
7=eclipsehelp 
8=tocjs 
9=troff

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: Current File Option (OT 1.x)

The Current File option of the Generate Output command lets you generate output from the current topic or map. The information about the current file and project are passed to the Ant script through command line parameters.

By default DITA-FMx provides support for 8 publishing targets. To add or modify this list, edit the BuildFile section of the ditafmx.ini file and modify the entries in the ditafmx-ant.xml file. The following is the default BuildFile section after completing the basic setup:

[BuildFile] 
EnvironmentSetup=C:\DITA\DITA-OT1.8.5\ditafmx-startcmd.bat 
DitaDir=C:\DITA\DITA-OT1.8.5\ 
AntCommand=ant 
AntScript=ditafmx-ant.xml 
Count=8 
1=xhtml 
2=html5 
3=pdf 
4=htmlhelp 
5=javahelp 
6=eclipsehelp 
7=tocjs 
8=troff

Each of the numbered entries corresponds to a target defined in the ditafmx-ant.xml file. If you want to add additional targets, add it to the ditafmx-ant.xml file, then add the corresponding target name to the BuildFile section (don’t forget to update the Count parameter).

Note: If you’re using a version of the DITA-OT earlier than 1.6, you’ll be prompted to enter the version number during OT setup (in the DITA Options dialog). This assigns that value to the BuildFile/OTVer key in the ditafmx.ini file.

[BuildFile] 
AntCommand=ant 
EnvironmentSetup=C:\DITA\DITA-OT1.8.5\ditafmx-startcmd.bat 
DitaDir=C:\DITA\DITA-OT1.8.5\ 
EnvironmentSetup-chm=C:\DITA\DITA-OT1.8.5-MYCHM\ditafmx-startcmd.bat 
DitaDir-chm=C:\DITA\DITA-OT1.8.5-MYCHM\ 
AntScript=ditafmx-ant.xml 
Count=9 
1=xhtml 
2=html5 
3=pdf 
4=chm 
5=htmlhelp 
6=javahelp 
7=eclipsehelp 
8=tocjs 
9=troff

Generate Output: Selected Target Option (OT 1.x only)

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

Copy the PROJECT.xml file to your DITA-OT directory and rename it something appropriate for your project.
Edit the <project>.xml file and set the properties indicated in the comments so they match your system and project.

Set up the ditafmx.ini file as follows:

notes:

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. (If this is not added, the default setting in the BuildFile section will be used.)
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

[AntBuild] 
Count=3 
1=<PROJECT> - CHM 
2=<PROJECT> - HTML 
3=<PROJECT> - PDF 
 
[ANT:<PROJECT> - CHM] 
BuildFile=C:\DITA-OT1.5.4\<PROJECT>.xml 
EnvironmentSetup=C:\DITA-OT1.5.4\ditafmx-startcmd.bat 
Target=chm 
OutputDir=C:\Projects\<PROJECT>\out\chm 
Logfile=C:\Projects\<PROJECT>\ant-buildlog-chm.txt 
 
[ANT:<PROJECT> - HTML] 
BuildFile=C:\DITA-OT1.5.4\<PROJECT>.xml 
EnvironmentSetup=C:\DITA-OT1.5.4\ditafmx-startcmd.bat 
Target=html 
OutputDir=C:\Projects\<PROJECT>\out\html 
Logfile=C:\Projects\<PROJECT>\ant-buildlog-html.txt 
 
[ANT:<PROJECT> - PDF] 
BuildFile=C:\DITA-OT1.5.4\<PROJECT>.xml 
EnvironmentSetup=C:\DITA-OT1.5.4\ditafmx-startcmd.bat 
Target=pdf 
OutputDir=C:\Projects\<PROJECT>\out\pdf 
Logfile=C:\Projects\<PROJECT>\ant-buildlog-pdf.txt