Understanding the Output Generator process

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.

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

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, etc. (Mandatory.)
  • Conditions: List of conditions to apply to the source DITA files to transform. These conditions are set up in the Output Generator configuration files. (Optional.)
  • 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: Contains temporary files created during the output generation process.
  • 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 generation process

The following diagram shows how the Output Generator process interacts with the DITA CMS components and how it uses the different configuration files to determine the transformation scenario and execute it.

Figure 1. Output Generator process Output Generator detailed process
  1. In the DITA CMS Eclipse Client, the user right-clicks an object and selects Generate Output.
  2. The DITA CMS Eclipse Client requests the available output types and user parameters from the Output Generator over the network.
  3. The Output Generator looks up the outputtypes.xml file to get the list of output types defined.
  4. It also looks up the preprocessors.xml file to get the list of user parameters to display to the user, if any.
  5. The Output Generator sends all the output types available as well as the user parameters for each output type to the DITA CMS Eclipse Client.
  6. The DITA CMS Eclipse Client retrieves the list of Ditaval files available from the TEXTML Server.
  7. The Output Generator dialog is displayed, with the following information:
    • Available output types
    • List of conditions and condition values used in the documents to transform
    • User-defined fields (also called user parameters)
    • DITAVAL field
    The following diagram shows a sample Output Generator window:
    Sample Output Generator dialog
  8. Based on the output type selected (either as entered by the user or from the previous Generate Output request), the DITA CMS Eclipse Client searches the TEXTML Server to retrieve the condition values for this output type (for example, audience, platform, etc.).
    Note: If there are many topics to transform (for example, if the user transforms a map that has a thousand topics), this step can take a few seconds since the TEXTML Server must scan each topic to get the list of conditions.
  9. The user selects the conditions and user parameters/Ditaval file, if any, and clicks Create.
  10. If the user entered a Ditaval file, the DITA CMS Eclipse Client retrieves the content of the Ditaval file from the TEXTML Server.
  11. The DITA CMS Eclipse Client sends the following information to the Output Generator:
    • Output type selected
    • Object ID
    • Object type
    • TEXTML Server, docbase, and collection that contain the files to transform
    • Monitoring port on which the dialog box will listen for updates from the Output Generator (if applicable)
    • Conditions selected by the user (if applicable)
    • Content of the Ditaval file (if applicable)
    • User parameter values (sent in the buildproperties file)
  12. Based on the output type specified by the user, the Output Generator looks up the outputtypes.xml file to determine the processors to run for this output type.
    For example, consider the following outputtypes.xml file:
    <outputtype name="Dita2Pdf" timeout="60000" system="false">
          <preprocessor name="Conditions"/>
          <preprocessor name="dita2pdf" />
    In this example, the Conditions and dita2pdf processors are associated to the Dita2Pdf output type.
  13. The Output Generator looks up file inputtypes.xml to determine how to retrieve the object to process from the TEXTML Server.

    This file specifies the method to run to extract the object from the database, since each object type is handled differently. For example, if the Generate Output command is specified on a map, then the map and all its containing objects must be retrieved from the TEXTML Server. However, if the Generate Output command is specified on a resource, then only that resource is retrieved.

  14. The Output Generator retrieves from the TEXTML Server the files to transform and stores them in memory.
  15. If conditions were specified by the end user in the Output Generator dialog, the Output Generator applies these conditions and removes from memory the content that does not meet these conditions.
  16. The Output Generator saves the files to a temporary working directory.
    Note: See Temporary Output Generator files for a description of the files saved to this directory.
  17. The Output Generator looks up the preprocessors.xml file to retrieve the conductor file and target to execute for each processor.
    For example, the dita2pdf preprocessor has the following configuration in the preprocessors.xml file:
    <preprocessor name="dita2pdf" class="com.ixiasoft.outputgenerator.preprocessor.AntProcessor" >
             <parameter name="outputfile" value=".pdf"/>
             <parameter name="buildfile" value="/conductor-ot.xml"/>
             <parameter name="target" value="dita2pdfwrapper"/>
             <parameter name="clean" value="clean"/>
             <parameter name="keep.log.files" value="true"/>

    So for this preprocessor, the Output Generator must execute the dita2pdfwrapper target from the conductor-ot.xml file.

  18. The Output Generator loads and executes the target.
  19. The target performs the transformation.

    When the transformation is completed, the control is returned to the Output Generator.

  20. If the keep.log.files parameter is set to true in the preprocessors.xml file, the Output Generator copies log files from the temporary working directory to the output directory.
  21. The Output Generator zips the contents of the output directory.
  22. The Output Generator returns the zip file to the dialog box.
  23. If the clean parameter is set to clean in the preprocessors.xml file, the Output Generator deletes the temporary working directory.