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
- Install the
Web Author Publishing plugin that can be
found in the . The plugin has a version in a format like
webpage
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. - The Web Author Publishing plugin
requires the
fontconfig
package to be installed. It can be installed by running the following command:sudo apt-get install font-config
- 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.
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.
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
- 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 Export as PDF action. In this case, however, the links between topics will not work. and then using the
- 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
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.
java.security.AccessControlException: access denied("java.io.FilePermission" "/path/to/directory" "read)
permission java.io.FilePermission "path/to/directory", "read";
A similar approach can be used when the PDF creation process cannot access system properties.
access: access denied ("java.util.PropertyPermission" "java.system.property.name" "read")
permission java.util.PropertyPermission "java.system.property.name" ,"read";