Advanced topic: The Output Generator process in detail

The following diagram shows in detail 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.

Note: You do not need to know these details to create transformation scenarios.
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
    • 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 (if you are using the deprecated Conditions preprocessor) as well as the values of user parameters of type index, if any.
    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/parameters as well as the list of the object's children.
  9. The user selects the 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, Content Store, 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)
    • 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="dita2pdf" />
    In this example, the dita2pdf processor is 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 retrieve the object from the Content Store, 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 (deprecated) 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 the job 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="buildfile" value="/conductor-ot.xml"/>
             <parameter name="target" value="dita2pdfwrapper"/>
             <parameter name="clean" value="job_postprocess"/>
             <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 conductor file loads and executes the target.
  19. During the execution of the target, the target forks a JVM to run the OT transformation in it.

    When the OT transformation is completed, the JVM is closed and the control is returned to the target.

  20. The target executes any post-processing instructions and returns the control to the Output Generator.
  21. If the keep.log.files parameter is set to true in the preprocessors.xml file, the Output Generator copies log files from the job directory to the output directory.
  22. The Output Generator zips the contents of the output directory.
  23. The Output Generator returns the zip file to the dialog box.
  24. The Output Generator executes the target defined in the <clean> element in the preprocessors.xml file. By default, this is the job_postprocess target.