DITA Map to PDF WYSIWYG Transformation

Oxygen XML Developer comes bundled with a DITA OT 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 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 supports the following processors (not included in the Oxygen XML Developer installation kit):

Oxygen Chemistry - A built-in processor that is bundled with Oxygen XML Developer. For more information, see the Oxygen PDF Chemistry User Guide.
Prince Print with CSS - A third-party component that needs to be purchased from http://www.princexml.com.
Antenna House Formatter - A third-party component that needs to be purchased from http://www.antennahouse.com/antenna1/formatter/.

The DITA-OT 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, 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:

Click the Configure Transformation Scenario(s) button.
Select DITA Map PDF - WYSIWYG.
In the CSS Processor tab, choose the processor type. You can select between Oxygen PDF Chemistry, Prince XML, or Antenna House.
In the Parameters tab, configure any of the following parameters (if applicable):
- 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 list of CSS URLs to be used in addition to those specified in the dita.css.list parameter.
Click OK and run the transformation scenario.

Customizing the Styles (for Output and Editing)

If you need to change the styles in the associated CSS, make sure you install Oxygen XML Developer in a folder where you have full read and write privileges (for instance, your user home directory). This is due to the fact that the installed files are usually placed in a read-only folder (for instance, in Windows, Oxygen XML Developer is installed in the Program Files folder where the users do not have change rights).

To change the styles of an 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.

Use the args.css parameter that allows you to specify a list of CSS URLs to be used in addition to the dita.css.list parameter:
1. Configure a DITA map to PDF WYSIWYG transformation scenario, as described in the procedure above.
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.

Tip: For more information about customizing CSS styles for PDF output, see the Oxygen PDF Chemistry User Guide. It offers numerous tips for customizing CSS styles even if you are not using the Chemistry processor.

How to Make Remote Resources Appear in the Output When Using the Prince Processor

If your documentation references external resources (such as images that are stored on a Web-based repository) and your system is behind an HTTP(S) proxy, you may find that they do not appear in the output when using the Prince Print with CSS processor. To solve this, follow this procedure:

Edit the build.xml file that is located in DITA-OT-DIR/plugins/com.oxygenxml.pdf.css.

There are two instances in the file where a pair of arguments are commented out:

   <!-- Please remove the comment wrapping the following two arguments
   if you are behind a proxy and your documentation refers remote resources,
   for example images. 
      
   Note: You also need to remove the backslash '\' that appears before the 
   property name: "http-proxy". That backslash is there because a sequence of 
   two dashes ('-') is not permited inside a comment.
   -->
   <!--
     <arg value="-\-http-proxy=${http.proxyHost}:${http.proxyPort}"/>
     <arg value="-\-http-proxy=${https.proxyHost}:${https.proxyPort}"/>
   -->

Remove the comment in both instances.
Make sure you also remove the slash that appears before the property name http-proxy in each instance.
Step Result: The arguments should now look like this:
```
  <arg value="--http-proxy=${http.proxyHost}:${http.proxyPort}"/>
  <arg value="--http-proxy=${https.proxyHost}:${https.proxyPort}"/>
```
Save the build.xml file.
Run the DITA map to PDF WYSIWYG transformation scenario.
Result: Your external resources should now appear in your output.

Customizing CSS Styles Using Oxygen PDF Chemistry

Oxygen PDF Chemistry makes it very easy to style and customize the PDF output of your DITA projects without having to work with xsl:fo customizations. It allows you to style the PDF output by simply changing the CSS and then re-running the transformation scenario until you get the desired result.

For more information, see the Oxygen PDF Chemistry User Guide. It also offers numerous tips for customizing CSS styles for PDF output even if you are not using the Chemistry processor.