Table of Contents
More Resources
Configuring the DITA Open Toolkit
Configuring the DITA Open Toolkit in easyDITA
Learn how to configure the DITA Open Toolkit in easyDITA to customize your output.
Set up a Publishing Scenario
Before you can publish with the DITA Open Toolkit, an administrator needs to set up publishing scenarios that will be selected by users to publish DITA topics and maps.
Set a DITAVal File for a Publishing Scenario
Add a DITAVal file, which is used for conditional processing, into a publishing scenario so it's applied each time the publishing scenario is used.
Build and Add Plugins
Build and Add Plugins , Upload a Plugin
Use Your Own DITA OT
Simple rules about using an uploaded DITA OT.
Use Your Own Ant Build File
easyDITA supports custom Ant build files, but there are some key points you must adhere to for it to work. 
Some things to look out for with FOP 
Notes for dealing with FOP customizations. 
Configuring the DITA Open Toolkit in easyDITA

Learn how to configure the DITA Open Toolkit in easyDITA to customize your output.
easyDITA provides full DITA Open Toolkit support right out of the box and is extremely flexible when it comes to setting up the DITA Open Toolkit.
When publishing using the DITA Open Toolkit, you must set up a publishing scenario in order to publish. You can make simple configurations when you Set up a Publishing Scenario. Think of a publishing scenario as a template. At publish, you can select a template to customize the output based on the parameters set in the template.
For example, you can create a publishing scenario using the following parameters:
  • Use DITA-OT1.8.4
  • Generate PDF output
  • Generate HTML output
For more advanced configuration and customization, you can upload your own plugins or completely new instances of the DITA Open Toolkits into easyDITA. Then you can include these plugins or new instances of the DITA Open Toolkit in a publishing scenario.
This guide will show you how to:
Set up a Publishing Scenario

Before you can publish with the DITA Open Toolkit, an administrator needs to set up publishing scenarios that will be selected by users to publish DITA topics and maps.
If you’re setting up a publishing scenario with a custom DITA-OT plugin, you’ll need to Upload a Plugin and Upload a DITA-OT before creating the publishing scenario.
You’re logged in as an administrator in the Dashboard interface and want to set up a publishing scenario.
  1. Under Administration, click Plugins.

    Step Information

    Expected Result
    The Plugins interface displays.

  2. Select DITA Open Toolkit.

    Expected Result
    The Configure the DITA Open Toolkit Plugin screen displays and lists all available scenarios, DITA OTs, and plugins.

  3. In the Scenarios list, click New.

    Expected Result
    The Add a New Publishing Scenario screen displays.

  4. In the Add a New Publishing Scenario screen, do the following:

    1. Enter a Scenario Name. This will be visible to end users when selecting a scenario in the Publication Manager
    2. Select the DITA Open Toolkit to use with this scenario.

      Step Information
      Remember:If you’re using a custom plugin in this scenario, you’ll also need to upload the correspending DITA Open Toolkit version the plugin is built on. For more information, see Upload a DITA-OT.
    3. Select an Ant file to run. Click Change, then select the Build file from the File Picker.

      Step Information
      Note:The default Ant script is “build.xml” in the root of the DITA OT folder.

  5. Click Add a Parameter.

    Step Information

    1. Enter a Parameter Name.

      Step Information

      Parameters must be expected by the Ant file you chose to run. If you selected the default build.xml in the DITA OT, there is a link to the DITA OT Parameter Reference in the right column of the Add a New Publishing Scenario screen.

      Example

      A common parameter is transtype. It lists the transformation types available in the toolkit (e.g. PDF, HTML Help, xhtml, etc.).

    2. Select a Parameter Type.

      Step Information

      There are four parameter types:

      1. Simple String Value
      2. User Select Box
      3. File Reference
      4. Runtime File Picker
      Example

      For the parameter transtype the Parameter Type is User Select Box, which will list a drop down of the transform types.

    • For a Simple String Value, enter a Value. You can allow users to modify a simple string value at publish by selecting the User Settable option.
    • For a User Select Box, you will need to add the Options you want to be present in the Select Box. For each option in the list box, click Add Option, then enter the text that will appear for that option in the list.
    • For a File Reference, click Change to choose a file with the File Picker. You may select files or folders with the file reference.
  6. To add additional parameters, click Add a Parameter, and repeat Step 5.
  7. (Optional) Under Select DITA OT Plugins, select a plugin.

    Step Information
    Remember:If you want to use a plugin in this scenario, you’ll need to Upload a Plugin first.
  8. Once you’ve specified all of the parameters for this scenario, click Save.

    Example
    Here’s an example of a publishing scenario:
    Expected Result

    You return to the Configure the DITA Open Toolkit Plugin screen and your new scenario is listed in the Scenarios list.

The new publishing scenario is now available for users to choose when publishing using the DITA Open Toolkit.
Set a DITAVal File for a Publishing Scenario

Add a DITAVal file, which is used for conditional processing, into a publishing scenario so it’s applied each time the publishing scenario is used.
You’re logged in as an administrator in the Dashboard interface and have a DITAVal file that you want to add to a publishing scenario.
  1. Create a ZIP folder containing the DITAVal file.
  2. Under Administration, click Plugins.

    Step Information
    Expected Result
    The Plugins interface displays.
  3. Select DITA Open Toolkit.

    Expected Result
    The Configure the DITA Open Toolkit Plugin screen displays and lists all available scenarios, DITA OTs, and plugins.
  4. In the DITA OT Plugins list, click New.

  5. Click Browse and then navigate to and select the ZIP folder.
  6. In the Scenarios list, click on an existing publishing scenario or click New to create a new one.
  7. Click Add a Parameter.

    Step Information
    click-add-parameter-in-edit-DITAOT-publishing-scenario-5
  8. Set the Parameter Name as “args.filter” and the Parameter Type as File Reference. 

    argsfilter

  9. Click Change and then navigate to and click on the DITAVal file.

  10. Click Save.
Your DITAVal file will be used whenever this scenario is run.
Use Your Own DITA OT

Simple rules about using an uploaded DITA OT.
easyDITA allows you to upload your own DITA OT. It’s a fairly simple process, just follow these rules:
  • Use one of the DITA-OT[version]_full_easy_install_bin.zip packages. The “Full Easy Install” packages contain integration hooks that easyDITA relies on.
  • When creating the ZIP folder, it should only contain the DITA OT directory in the root.

    Caution:Having other directories in parallel with the DITA OT may cause the extraction process to create the improper structure. An easy way to ensure your ZIP archive is correct is to right click the DITA OT directory and select your operating system’s create ZIP option.
To upload your DITA OT, click New next to Available DITA Open Toolkits in the Plugin Manager and upload your zip file.
Use Your Own Ant Build File

easyDITA supports custom Ant build files, but there are some key points you must adhere to for it to work. 

Mandatory Parameter Values

easyDITA communicates with the DITA OT using the command line and always passes two parameters to the specified Ant build file. These parameters are “args.input” and “output.dir”. Because easyDITA runs the entire process dynamically, there is no way to predict where the input files will be prior to processing, which is why easyDITA supplies the args.input at run time. 
When creating a custom Ant build file make sure the < property /> tags for args.input and output.dir appear as follows:
  • < property name=”args.input” value=”${args.input}”/>
  • < property name=”output.dir” value=”${output.dir}”/>
This will pass the proper values from the command line, where easyDITA supplies them, into the DITA Open Toolkit.
Here is a simple example configuration: 
< project name="example" default="dita2example"> 
...
  < !-- Allow the build process access to environment variables --> 
  < property environment="env"/> 
  < !-- Set toolkit directory from environment variable --> 
  < property name="toolkit_dir" value="${env.DITA_DIR}"/> 
...
  < target name="dita2example"> 
    < ant antfile="${toolkit_dir}${file.separator}conductor.xml" target="init"> 

      < property name="args.input" value="${args.input}"/> 
      < property name="output.dir" value="${output.dir}"/> 

    < /ant> 		  
  < /target> 
< /project> 

Other key points 

  • Don’t worry about running the integrator, easyDITA automatically runs it prior to every publish.
  • Always use the ${env.DITA_HOME} as the reference to your DITA OT.
  • Don’t set the args.logdir; easyDITA takes care of this dynamically. Setting this variable can (and often will) lead to publishing failures which are hard to detect.
Some things to look out for with FOP 

Notes for dealing with FOP customizations. 

Sourcing images

  • When sourcing images in a FOP customization it’s important to remember that the present-working-directory is always the DITA OT directory. So, if you’re expecting to have images in your FOP xsl that rely on running a build from a specific directory, it must be the DITA OT directory.
  • easyDITA runs on Linux servers. Linux uses forward slashes in its paths (“/”), using Windows style backslashes (“\”) in paths will cause problems.