Installing the DITA For Publishers Package

The DITA For Publishers materials are provided as a single Zip package from the project's download page: https://sourceforge.net/projects/dita4publishers/files/. The Toolkit plugins are intended for use with the 1.5, 1.6, and 1.7 versions of the Open Toolkit but may work with the 1.4.3 version. The DITA for Publishers plugins are tested against the latest stable and milestone releases. Note that release 1.5.4 fixes a number of bugs from 1.5.3. The 1.5.4 release has proven stable for me and I recommend moving to that release if at all possible. Note that for 1.7 there are a few minor code differences from 1.6 that require a separate build of the D4P plugins, identified by "OT17" in the materials package filename.

  1. Download the Zip package and unpack it wherever you like, e.g. c:\myprojects\dita4publishers.
  2. Unzip the package.
    You should get these directories and zip files:
    dita4publishers_toolkit_plugins-version-release-modification.zip
    Contains the DITA for Publishers Toolkit plugins. To be installed in your local Open Toolkit's plugins directory.
    documentation
    Contains the project documentation (DITA format).
    sample_data
    Contains sample publications and related data that serve to demonstrate and test the Publishing vocabulary modules.
    xslt
    Contains various XSLT transforms that might be useful, mostly used to convert Project Gutenberg sample data into publications (the XSLTs used by plugins are in the plugins as packaged).
  3. Unzip the file dita4publishers_toolkit_plugins into your local Open Toolkit's plugins directory so that each top-level directory in the Zip file is a direct child of plugins.
    Your plugins directory should include a number of DITA for Publishers plugin directories, including:
    • net.sourceforge.dita4publishers.doctypes
    • net.sourceforge.dita4publishers.epub
    • net.sourceforge.dita4publishers.kindle
    • net.sourceforge.dita4publishers.pubmap.html
    • net.sourceforge.dita4publishers.word2dita
    • net.sourceforge.dita4publishers.xmldomain.doctypes
    • net.sourceforge.dita4publishers.xmldomain.html
  4. Run the Toolkit's integrate Ant target to integrate the new plugins into the toolkit.

    There are many ways to do this, but one way is to use a command window. Navigate to your Open Toolkit's directory and then issue this command:

    tools/ant/bin/ant -f integrator.xml

    That should run and you should see some sort of happy message.

    Note: The Open Toolkit that comes installed with OxygenXML does not include Ant in the tools/ant location within the Toolkit because OxygenXML already provides Ant in a different location. As of Oxygen 13.1, Ant is in tools/ant below the main Oxygen installation directory. If you are in a command window with Oxygen's Toolkit as your current directory, you would do this:
    c:\Program Files\oxygen\frameworks\dita\DITA-OT > ..\..\..\tools\ant\bin\ant -f integrator.xml
  5. Test the toolkit by running the epub generation on one of the sample publications.
    You first need to start a Toolkit-specific command window, which you do by running the command startCmd.bat (Windows) or startCmd.sh (OSX, Linux). This sets up the Java class path so the Toolkit processes will work correctly:
    c:\DITA-OT > startCmd.bat

    The, using the command window you just created, this command should work:

    java -jar lib/dost.jar /i:/Users/myname/dita4publishers/sample_data/wizard-of-oz/wizard-of-oz.ditamap /transtype:epub

    Specifying the actual path to where you put the sample data.

    For Windows, use backslashes in the filename in the /i parameter:
    java -jar lib/dost.jar /i:\Users\myname\dita4publishers\sample_data\wizard-of-oz\wizard-of-oz.ditamap /transtype:epub