DITA Map to PDF WYSIWYG Transformation Scenario

Oxygen XML Developer comes bundled with a DITA Map to PDF WYSIWYG transformation scenario based on a DITA-OT CSS-based PDF Publishing plugin that allows you to convert DITA maps to PDF using a CSS layout processor. Oxygen XML Developer also comes bundled with a built-in CSS-based PDF processing engine called Oxygen PDF Chemistry. For those who are familiar with CSS, this makes it very easy to style and customize the PDF output of your DITA projects without having to work with xsl:fo customizations. Oxygen XML Developer also supports a few third-party processors.

The following processors are supported:

The DITA-OT CSS-based PDF Publishing plugin is located in the following directory: DITA-OT-DIR/plugins/com.oxygenxml.pdf.css. Although it includes a set of CSS files in its css subfolder, when this plugin is used in Oxygen XML Developer (using the DITA Map to PDF WYSIWYG transformation scenario), the CSS files located in the ${frameworks} directory take precedence.

Creating the Transformation Scenario

To create an DITA Map to PDF WYSIWYG transformation scenario, follow these steps:
  1. Click the Configure Transformation Scenario(s) button.
  2. Select DITA Map PDF - WYSIWYG.
  3. In the CSS Processor tab, choose the processor type. You can select between Oxygen PDF Chemistry, Prince XML, or Antenna House.
  4. In the Parameters tab, configure any of the following parameters (if applicable):
    • css.processor.path.chemistry (if you are using the Oxygen PDF Chemistry processor) - Specifies the path to the Oxygen PDF Chemistry executable file that will be run to generate the PDF. If this parameter is not set, your system's PATH environment variable will be used to find and start the Oxygen PDF Chemistry processor.
    • css.processor.path.prince (if you are using the Prince Print with CSS processor) - Specifies the path to the Prince executable file that will be run to produce the PDF. If you installed Prince using its default settings, you can leave this blank.
    • css.processor.path.antenna-house (if you are using the Antenna House Formatter processor) - Specifies the path to the Antenna House executable file that will be run to produce the PDF. If you installed Antenna House using its default settings, you can leave this blank.
    • show.changes.and.comments - When set to yes, user comments, replies to comments, and tracked changes are published in the PDF output. The default value is no.
    • dita.css.list - Allows you to specify a list of CSS URLs to be used by the PDF processor (instead of the default CSS files). The files must have URL syntax and be separated using semicolons.
    • args.css - Allows you to specify a path to a custom CSS to be used in addition to those specified in the dita.css.list parameter.
  5. Click OK and run the transformation scenario.

Customizing the Output

The DITA-OT CSS-based PDF Publishing plugin makes it very easy to style and customize the PDF output of your DITA projects without having to work with xsl:fo customizations. You can style the PDF output by simply using a custom CSS to change the styling and then re-running the transformation scenario until you get the desired result.

For more information, see the DITA Map to PDF: Customization CSS section. It offers numerous tips and examples for customizing the CSS for the PDF output.

Changing the Style of an Element

To change the style of a particular element, you need to create an additional CSS file that will store the customization rules. Once you have created this file, you need to instruct the editor how to use this additional CSS.

  • Specify the path to your custom CSS using the args.css parameter:
    1. Edit a DITA map to PDF WYSIWYG transformation scenario.
    2. In the Parameters tab, specify the path to your custom CSS files in the args.css parameter.
    3. Click OK and run the transformation scenario.

    This method is appropriate if you just want to apply the styling customization to the output.