Setting Up to use the Generate Output Command

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 calls to the DITA Open Toolkit (DITA-OT) through a batch file (named ~ant-build.cmd) that 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 defined globally. This is particularly an issue if you are using DITA-OT 1.3 or later, since these versions provide a batch file that sets the environment variables at run time. To test for proper environment variable settings, open a command shell (choose Start > Run, then enter “cmd” and press Enter). In the command shell enter the following to list the version information for each utility. If you get a message “command unknown” the environment variables are not set up properly for DITA-FMx.

C:\Documents and Settings\Joe User>ant -version 
Apache Ant version 1.6.5 compiled on June 2 2005

C:\Documents and Settings\Joe User>java -version 
java version "1.6.0" 
Java(TM) SE Runtime Environment (build 1.6.0-b105) 
Java HotSpot(TM) Client VM (build 1.6.0-b105, mixed mode)

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 add a new DitavalFiles section to the ditafmx.ini file. This section specifies a “friendly name” and the actual path and file name for one or more ditaval files. These ditaval files are also used by the Apply Ditaval As Conditions command.

[DitavalFiles] 
OnlineProd1=C:\PATH\online-prod1.ditaval 
OnlineProd2=C:\PATH\online-prod2.ditaval

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:

    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.

    • 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.3.1\<PROJECT>.xml 
EnvironmentSetup=C:\Projects\ot-setup.cmd 
Target=chm 
OutputDir=C:\Projects\<PROJECT>\out\chm 
Logfile=C:\Projects\<PROJECT>\ant-buildlog-chm.txt 
 
[ANT:<PROJECT> - HTML] 
BuildFile=C:\DITA-OT1.3.1\<PROJECT>.xml 
Target=html 
OutputDir=C:\Projects\<PROJECT>\out\html 
Logfile=C:\Projects\<PROJECT>\ant-buildlog-html.txt 
 
[ANT:<PROJECT> - PDF] 
BuildFile=C:\DITA-OT1.3.1\<PROJECT>.xml 
Target=pdf 
OutputDir=C:\Projects\<PROJECT>\out\pdf 
Logfile=C:\Projects\<PROJECT>\ant-buildlog-pdf.txt
Parent topic: Installation and Setup