Understanding transformation scenarios

To transform a DITA object, you create a transformation scenario.

A transformation scenario is a set of commands and properties that convert source DITA files into an output format such as PDF, HTML, etc.

Many transformation scenarios use the DITA Open Toolkit, which is a set of open source tools used to transform DITA objects, but you can use any other tool or script to transform your content.

By default, the IXIASOFT CCMS provides five transformation scenarios that are available to the end user and four transformation scenarios that are used by the system.

User transformation scenarios

User transformation scenarios allow users to generate their output in specific formats. The IXIASOFT CCMS provides five user transformation scenarios:
  • Dita2Pdf Generates PDF documents from objects.
  • Dita2EclipseHelp: Generates Eclipse help from objects.
  • Dita2htmlhelp: Generates HTML help (.chm file) from objects.
  • Dita2xhtml: Generates HTML files from objects.
  • Export: Exports topics so that they can be reused in another project. (Note that in the default configuration, this output type is available to System Administrators only).
    Note: If you are using the DRM module, use the Export [DRM] transformation scenario.

System transformation scenarios

System transformation scenarios are used by the CCMS to generate output for features such as localization and reviewing. System transformation scenarios are not available to users and do not appear in the Generate Output dialog. The CCMS provides four system transformation scenarios:

  • Dita2ReviewPdf: Generates PDF versions of topics for review during the Edit/Review cycle.
  • Dita2TranslationPdf: Generates PDF versions of topics during the Localization cycle.
  • Dita2RedlinePdf Compares a map with an earlier version of itself. The output file highlights modified and/or deleted text using colors defined in a configuration file.
  • Dita2xhtml.preview: Generates the preview for snapshots.
  • BuildManifest: Generates the output for a Build Manifest.

Creating a transformation scenario

The process for creating a transformation scenario with the Output Generator is always the same, whether you are using the DITA Open Toolkit or another build script:

  1. Add targets to the conductor file: The conductor file contains the sets of Apache Ant tasks (called targets) to execute for the transformation scenario. This is where the transformation occurs. You can write a target using any standard Apache Ant tasks and properties or you can use the IXIASOFT custom Ant properties, targets, and tasks.
  2. Create a new preprocessor in the file preprocessors.xml: The preprocessor links the conductor file used to transform the content to the output type selected by the user. Preprocessors also define system and user parameters that apply to the transformation process.
  3. Create a new output type in the file outputtypes.xml: This file defines the types of output into which users can transform their DITA files (for example, PDF, HTML, etc.). If you make the transformation scenario visible to the end user, then the output type is displayed in the Output Generator dialog, and users can select it when generating their outputs. Each <outputtype> defined in the outputtypes.xml file points to a <preprocessor> in the preprocessors.xml file.

For example, consider a very simple transformation scenario that extracts the raw DITA content from the CMS and stores it in the zip file returned by the Output Generator. This is the Export output type displayed in the Generate Output dialog box.

As shown in the diagram below, when the user selects Export from the Output Generator dialog, the Output Generator looks up the outputtypes.xml file to determine the preprocessor associated with this output type. Using the preprocessor name (export), it then looks up the preprocessors.xml file to determine the conductor file that contains the target to execute (conductor-ixia.xml) as well as the target to execute (export).

The actual code that performs the transformation is found in the target. In the example below, this target simply copies the source files from the source job directory and copies them to the output directory.
Create a transformation scenario
To create a transformation scenario in the Output Generator, you:
  1. Create a new target in the conductor file.
  2. Create a new preprocessor in the preprocessors.xml file.
  3. Create a new output type in the outputtypes.xml file.