Show Page Sections

Local DITA-OT Overview

You can install the DITA-OT publishing engine locally to quickly test and troubleshoot your plugins without the need to upload them to Heretto CCMS.

Overview

The DITA-OT is a command-line utility. You operate the local DITA-OT by using your operating system shell. The DITA-OT runs on Windows, macOS, and Linux.

Shell

Each major operating system has a built-in shell application that enables you to interact with the DITA-OT from the command line.

Figure 1. Windows Command Prompt.
Tip: You can open the command prompt by pressing the Start key and entering cmd
Windows Command Prompt
Figure 2. macOS Terminal.
Tip: You can open the terminal by pressing Cmd > Space and entering terminal
macOS Terminal
Figure 3. Linux Terminal.
Tip: On Ubuntu 19.10, you can open the terminal by pressing the Super key and entering terminal
Linux Terminal

Operation

You use the DITA-OT by entering dita at the command prompt followed by any applicable arguments.

Tip: For the complete list of the dita arguments, at the prompt, enter dita -h

Install DITA-OT Locally

The DITA-OT installation is slightly different for Windows, macOS, and Linux.

  1. In your web browser, go to https://www.dita-ot.org/dev/topics/installing-client.html.
  2. On the DITA-OT documentation site, from the Version drop-down list, select the DITA-OT version that you want to install.
    Figure 4. DITA-OT Documentation
    DITA OT Documentation Screenshot
    Remember: DITA-OT plugins may require specific versions of the DITA-OT publishing engine to operate properly. In Heretto CCMS, you can use different DITA-OT publishing engines and plugins in different publishing scenarios. We recommend using the current version of the DITA-OT publishing engine.
  3. Install the DITA-OT by using the instructions on the following DITA-OT site: https://www.dita-ot.org/dev/topics/installing-client.html.
    Important: For macOS and Linux, if possible, we recommend using Homebrew to install the latest DITA-OT.
  4. Ensure that you added the path to the DITA-OT bin directory to the PATH system variable. See Run the DITA Command from Anywhere.
  5. Open the shell application by doing one of the following:
    • For Windows, press the Start key and enter cmd
    • For macOS, press Cmd > Space and enter terminal
    • For Linux (Ubuntu 19.10), press the Super key and enter terminal
  6. At the prompt, ensure that you properly installed the DITA-OT by entering dita -v
    The version of the local DITA-OT appears.
    Local DITA OT screenshot

Run the DITA Command from Anywhere

Adding the DITA-OT to the PATH system variable enables you to run the dita command from any location in the system.

Install the DITA-OT publishing engine locally. See Install DITA-OT Locally.
Important: For macOS, if you installed the DITA-OT via Homebrew, you can skip this procedure.
  1. For Windows, do the following:
    1. Click Start and enter environment variables
    2. Select Edit the system environment variables.
    3. In the System Properties window, click Environment Variables.
    4. In the Environment Variables window, under System variables, double-click Path.
      Windows Environment Variables screenshot
    5. In the Edit environment variable window, click New.
    6. Enter <DITA_OT_bin_directory>
      Where: <DITA_OT_bin_directory> is the full path to the DITA-OT bin directory on your local drive.
      Edit Windows Environment Variable screenshot
    7. In each window, click OK.
  2. For macOS, do the following:
    1. Press Cmd > Space .
    2. Enter terminal
    3. Press Enter .
      macOS Command Terminal
    4. Enter sudo nano /etc/paths
    5. Enter the administrator password.
    6. At the bottom of the file, add the full path to the DITA-OT bin directory on your local drive.
      Enter: /Applications/dita-ot-3.4/bin
      macOS Command Terminal
    7. Press Control > X
    8. Press Y
    9. Press Enter .
    10. Close the Terminal window.

Install a DITA OT Plugin Locally

You can install a DITA-OT plugin by moving the plugin folder and running the dita --install command.

Before you begin, do the following:
  1. Install the DITA-OT publishing engine locally. See Install DITA-OT Locally.
  2. Obtain the plugin that you want to install on your local DITA-OT instance.
  1. Copy the plugin folder to the Plugins folder of the local DITA-OT.
    For example copy the plugin folder to:
    • C:\dita-ot-3.4\plugins (Windows)
    • /Applications/dita-ot-3.4/plugins (Mac)
  2. Open the shell application by doing one of the following:
    • For Windows, press the Start key and enter cmd
    • For macOS, press Cmd > Space and enter terminal
    • For Linux (Ubuntu 19.10), press the Super key and enter terminal
  3. Note: If you added DITA to the PATH system variable, you can skip this step.
    At the prompt, enter cd DITA_OT_bin_directory
    Where: DITA_OT_bin_directory is the full path to the DITA-OT bin directory on your local drive.
    For example, enter:
    • C:\dita-ot-3.4\bin (Windows)
    • /Applications/dita-ot-3.4/bin (Mac)
  4. At the prompt, enter dita --install
    The local DITA-OT updates the available plugins.
    Command Terminal

Publish Content with Local DITA-OT

You can transform the DITA source to various output formats by using a local instance of the DITA-OT.

Note: The following procedure shows the simplest dita command that you can use to publish content locally. For more information, see the DITA-OT documentation on https://www.dita-ot.org.
Before you begin, do the following:
  1. Install the DITA-OT publishing engine locally. See Install DITA-OT Locally.
  2. If needed, install the DITA-OT plugin that you want to use in publishing. See Install a DITA OT Plugin Locally.
  1. Open the shell application by doing one of the following:
    • For Windows, press the Start key and enter cmd
    • For macOS, press Cmd > Space and enter terminal
    • For Linux (Ubuntu 19.10), press the Super key and enter terminal
  2. Note: If you added DITA to the PATH system variable, you can skip this step.
    At the prompt, enter cd DITA_OT_bin_directory
    Where: DITA_OT_bin_directory is the full path to the DITA-OT bin directory on your local drive.
    For example, enter:
    • C:\dita-ot-3.4\bin (Windows)
    • /Applications/dita-ot-3.4/bin (Mac)
  3. Enter the following into shell: dita --input "dita_source_path" --format transtype --output "out_folder_path"
    Where:
    • dita_source_path is the full path to the map or a topic that you want to publish.

      Some DITA-OT plugins may require a map to publish content properly. If you want to publish a single topic, we recommend including it in a map and publishing that map.

    • transtype is the transformation type defined in the plugin that you want to use

      For example:

      • One of the default transtypes, including: pdf2, html5, or javahelp
      • Any custom transtype
    • out_folder_path is the full path to the output folder
    Example:
    dita --input "C:\LocalFiles\GitHub\XML\source\Technical_Writing_Environment_Setup_Guide\Technical_Writing_Environment_Setup_Guide.ditamap" --format html5 --output "C:\LocalFiles\GitHub\XML\source\Technical_Writing_Environment_Setup_Guide\out"
    Figure 5. Output Example
    DITA OT Output example