DITA Map to PDF WYSIWYG Transformation

Creating the Transformation Scenario

To create an experimental DITA map to PDF WYSIWYG transformation scenario, follow these steps:

1. Click the Configure Transformation Scenario(s) button from the Dita Maps Manager toolbar.
2. Select DITA Map PDF - WYSIWYG - Experimental.
3. In the Parameters tab, configure the following parameters:
   • 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. The files must have URL syntax and be separated using semicolons. If the value is empty, the current selection from the Styles drop-down menu is used.
   • 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 OR in addition to the CSS that is currently selected in the Styles drop-down menu. The files must have URL syntax and be separated using semicolons. Also, the dita.css.list parameter must be left empty to use these files in addition to the selection in the Styles drop-down menu.
4. 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 Editor plugin 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 Editor plugin 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. This can be done in two ways:

• Create an alternate CSS for the DITA document type:
  1. Follow the procedure for adding an alternate CSS file in Customizing the Main CSS of a Document Type.
  2. Once you have configured your CSS as an additional layer, you can select it from the Styles drop-down menu (on the toolbar).
  3. Run the DITA Map PDF - WYSIWYG - Experimental transformation scenario and the customization rules from the additional CSS will be visible in the produced PDF.

  This method allows you to have many customization CSS files and simply select the one that you need at any time for both the output and rendering Author mode while editing.

• 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.

Using the CSS Inspector to See Style Associated with an Element

To find the styles associated with an element, follow this procedure:

1. Open a document in the editor and select Inspect Styles from the contextual menu. This opens the CSS Inspector view that shows all the CSS rules that apply to the selected element.
2. Click the particular link for the CSS selector that you need to change and Oxygen XML Editor plugin will open the CSS file and position the cursor at that selector.
3. After you identify the source of the styles you want to modify, copy the CSS rule in your customization CSS file and modify it according to your needs.

   To see the changes in Author mode, press F5 to reload the document.

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:

1. Edit the build.xml file that is located in DITA_OT_DIR/plugins/com.oxygenxml.pdf.css.
2. 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}"/>
      -->

3. Remove the comment in both instances.
4. 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}"/>

5. Save the build.xml file.
6. Run the DITA map to PDF WYSIWYG transformation scenario.

   Result: Your external resources should now appear in your output.