Edit online

PDF Publishing Support

Oxygen XML Web Author supports exporting documents as PDF by using the Oxygen PDF Chemistry engine and the output can be easily customized through CSS. You can print the currently edited document as PDF or export it to PDF using an XML to PDF with CSS transformation scenarios defined in the framework that may contain special publishing styles.

Information about updates and new features for each version of Oxygen PDF Chemistry can be found on the What's New page.

Enabling PDF Support

The Web Author PDF support can be enabled by installing the Web Author Publishing plugin that can be found in the Download > Connectors/Plugins webpage. The plugin has a version in a format like MAJOR.MINOR.X.Y and it follows the Oxygen XML Web Author and Oxygen PDF Chemistry versioning scheme. Choose the last version that matches the major and minor version of your instance of Web Author. Make sure that you read and understand the terms and conditions of its end-user license agreement. Once installed and enabled, two actions are contributed to the Web Author interface (available in the More drop-down menu):
  • Print - Generates a PDF preview of the current document and prints it. The PDF is generated using the same CSS files used by the editor.
  • Export as PDF - Downloads a PDF version of the document based on the framework configuration:
    • By default, the editor styles are used.
    • If one or more XML to PDF with CSS transformation scenarios are configured, they appear in a sub-menu of the Export as PDF menu item. Those scenarios are based on Oxygen PDF Chemistry.

Notes About Configuring the Plugin in the Administration Page

The PDF generation invokes an external process on the server and resources for the process can be configured in the Administration Page, where you can configure:

  • The memory allocated to a publishing process.
  • The maximum number of concurrent publishing processes.
Note: The content communicated to and from the publishing process is encrypted.

Configuring the CSS

Since the conversion to PDF is done using Oxygen PDF Chemistry, it is based on the CSS files specified in the framework.

The Print action strictly uses the CSS files that are used to render the document in the editor. The Export as PDF action uses the CSS files defined in the XML to PDF with CSS transformation scenarios (an Oxygen PDF Chemistry scenario).
Note: Frameworks can be customized using Oxygen XML Editor/Author, from the Document Type Configuration dialog box.

Useful hints:

  • You can use @media print {} rules to configure CSS rules that apply only for generating PDF.
  • For DITA, a file located at css/webauthor/p-dita.css is also loaded along with the editor styles.
  • You can match an element based on its pseudo-classes. For example, to match a -oxy-expanded pseudo-class, you can use the following syntax: 
    @namespace oxy-pseudo "https://oxygenxml.com/ns/pseudo-elements/";
*[oxy-pseudo|p-oxy-expanded]) {
  ... 
}
  • You can use any CSS extension supported by the Oxygen PDF Chemistry engine.
  • The PDF generation engine will work on a resolved document. If your content uses DITA conrefs, XInclude, or another content reference mechanism, the references will be expanded before the file is sent to the CMS.
  • Links to other XML files will not work in the generated PDF. You may want to customize your CSS to handle this.
  • Fonts that cover the characters in the document have to be installed on the server that run Web Author. For example, see: Localization.

Limitations

While the PDF support can be very useful for quickly downloading your content as PDF, it has several limitations that needs to be considered:
  • For DITA documents, the PDF is not obtained by using DITA-OT (the most popular DITA publishing tool).
  • You can publish a whole DITA map by switching to Display Mode > Show Topic Content and then using the Export as PDF action. In this case, however, the links between topics will not work.
  • The PDF is obtained by applying a CSS and currently there is no support for generating additional content such as Table of Contents, List of Figures, etc.

Licensing

All the generated PDF files contain a watermark that consists of the Oxygen PDF Chemistry icon. To remove this watermark, you can configure the plugin using an Oxygen PDF Chemistry license key.

To add the license key, create a file named licensekey.txt in the [DATA-DIR]/options folder and paste the license key in this file.

Monitor Security Access

As mentioned above, the PDF publishing support uses the Oxygen PDF Chemistry engine to generate the PDF. If you want to monitor security access by generating verbose output, you can set the level of the CHEMISTRY_SECURITY_LOGGER to DEBUG level in the log4j configuration file:
<Logger name="CHEMISTRY_SECURITY_LOGGER" level="DEBUG"/>

Result: The java.security.debug=access,failure system property will be set.

Configure Security Policy

The PDF publishing plugin runs Oxygen PDF Chemistry with a security policy. The configuration file for the policy is found in: policy/chemistry-publishing.policy. The path is relative to the base directory of the plugin. The policy file can be modified to grant the Chemistry process permissions to access files, directories, and system properties.

Access errors are logged in the oxygen.log file and have the following format:
java.security.AccessControlException: access denied("java.io.FilePermission" "/path/to/directory" "read)
To fix the permission, the "path/to/directory" must be added to the policy file:
permission java.io.FilePermission "path/to/directory", "read";

A similar approach can be used when the PDF creation process cannot access system properties.

The logged error looks like this:
access: access denied ("java.util.PropertyPermission" "java.system.property.name" "read")
To fix the permission to access system properties, you would need to add the following configuration line to the policy file:
permission java.util.PropertyPermission "java.system.property.name" ,"read";