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 a Default 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.
Use Your Own DITA Open Toolkit
Simple rules about using an uploaded DITA Open Toolkit.
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 Toolkit 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 a Default 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.
context

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. In the Administration interface, click Plugins .

    Step Information

    Expected Result
    The Plugins interface displays.

  3. Select DITA Open Toolkit.

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

  4. In the DITA OT Plugins list, click New.

    Step Information

  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 .
  8. Set the Parameter Name as args.filter and the Parameter Type as File Reference

    Step Information

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

    Step Information

  10. Click Save .
result

Your DITAVal file will be used whenever this scenario is run. 

Use Your Own DITA Open Toolkit

Simple rules about using an uploaded DITA Open Toolkit.
easyDITA allows you to upload your own DITA Open Toolkit. 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 Open Toolkit directory in the root.

    Caution:Having other directories in parallel with the DITA Open Toolkit 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 Open Toolkit directory and select your operating system’s create ZIP option.
To upload your DITA Open Toolkit, click New next to Available DITA Open Toolkits list in the Plugins interface 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. 
section

Mandatory Parameter Values

easyDITA communicates with the DITA Open Toolkit 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> 

section

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 Open Toolkit.
  • 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. 
section

Sourcing images

  • When sourcing images in a FOP customization it’s important to remember that the present-working-directory is always the DITA Open Toolkit 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 Open Toolkit directory.
  • easyDITA runs on Linux servers. Linux uses forward slashes in its paths (“/”), using Windows style backslashes (“\”) in paths will cause problems.