Overview of the Output Generator process

The Output Generator is the DITA CMS component that executes the transformation processes from DITA files to a specified output type, such as PDF, HTML, XML, CHM, etc.

Transformation processes are called transformation scenarios in the Output Generator. The basic Output Generator installation provides five default transformation scenarios.

  • The Dita2Pdf scenario generates PDF documents.
  • The Dita2EclipseHelp scenario generates Eclipse help.
  • The Dita2htmlhelp scenario generates HTML help (.chm file).
  • The Dita2xhtml scenario generates HTML files.
  • The Export scenario exports DITA CMS topics so that they can be reused in another project.
    Note: If you are using the DRM module, use the Export[DRM] transformation scenario.

This section describes the Output Generator process. Understanding this process will help you configure the Output Generator for your transformation requirements.

There are three main concepts in the Output Generator process:
  • Output Generation dialog box
  • Configuration files
  • Output directories

Output Generation dialog

To generate the output of their DITA files, users select the map, topic, or image to transform and right-click Generate Output. This command triggers the process that will transform source DITA files into one of the output types configured.

The following diagram shows a typical Output Generator dialog, displayed when users select Generate Output:

Sample Output Generator dialog

This dialog allows users to specify the following:

  • Output type: Type of output into which the source DITA files will be transformed, such as PDF, Eclipse Help, HTML, Export, etc. (Mandatory.)
  • User parameters: Parameters that can be specified by users when generating the output. They can be used, for example, to determine which cover page to use on a PDF file. These parameters are set up in the Output Generator configuration files. (Optional.)
  • DITAVAL: Ditaval file to apply to the source DITA files to transform. These files are created using the DITA CMS. Note that if there are no ditaval files created, this field does not appear on the Generate Output dialog. (Optional.)

Configuration files

The Output Generator uses three main configuration files to determine the transformation scenario to execute:
  • Output type file (outputtypes.xml): Defines the types of output into which users can transform their DITA files (for example, PDF, HTML help, Eclipse help, etc.).
  • Preprocessor file (preprocessors.xml): Defines user parameters and links the output type selected by the user to the conductor file used to transform the content.
  • Conductor file (for example conductor-ot.xml): Contains the Apache Ant tasks (called targets) that will be executed to transform the source file.

Output directories

Two main directories are used during the output generation process:
  • Temporary working directory (also called job directory): Contains the source files extracted from the TEXTML Server.
  • Output directory: Contains the result of the output generation process (for example, the PDF file, HTML output, etc.) and may also contain the log files. This directory will be returned to the user.

Output Generator process

The following diagram show at a high-level how the Output Generator interacts with the other DITA CMS components to generate the output:
High-level Output Generator process
  1. In the DITA CMS Eclipse Client, the user right-clicks an object and selects Generate Output.
  2. The DITA CMS retrieves the available output types from the Output Generator and displays the dialog to the user.
  3. The user selects the output type, user parameters, and Ditaval file, as appropriate, and clicks Create.
  4. The DITA CMS sends the output information to the Output Generator.
  5. The Output Generator retrieves the files to transform from the TEXTML Server.
  6. The transformation scenario is executed.
  7. The Output Generator returns the zipped output to the user.
  8. The DITA CMS Eclipse Client displays a dialog allowing the user to save the job.