› KCM Core Scripting Language Developer's Guide › Commands › DocToPDF › Using Rendition

Using Rendition

Rendition is a native rendering engine included with KCM Core.

The advantages of using the Rendition engine:

  • It doesn't require a Microsoft Word installation on the KCM Core server.
  • It supports a wide range of conformance levels when generating PDF/A, including support for the PDF/UA standard.
  • It supports the generation of an outline tree based on the structure of the source document and produces named hyperlinks.
  • It includes the document title and subject as properties in the resulting PDF document.

The disadvantages of using the Rendition engine:

  • It doesn't support DOC documents. Only DOCX files are converted. Note, that the DOC format has been deprecated in KCM 5.7.0.
  • The resulting PDF document can differ slightly from the document produced by Microsoft Word, and some DOCX features are not supported. For additional information see the Limitations of Rendition section below.

The following parameters of DocToPDF are used to control PDF generation with Rendition engine:

Parameter

Required/Optional

Description

SubstitutionFont Optional

The font to use when a document has a font that is not present on the system. The setting only has effect if the Rendition engine is used. Possible values are:

  • *default Rendition uses Arial Unicode MS if it is installed on the system. If not, it uses the font specified as the default font for the document (usually Times New Roman).
  • *none Rendition does not substitute fonts but shows an error message when a font is not present.
  • Name of the substitution font. Rendition uses this font as a substitution. If it is not present, an error message is shown.

If this parameter is omitted, the default value of the Rendition.SubstitutionFont global setting is used. The default can be changed through the following setting in the dp.ini file: Rendition.SubstitutionFont

PDFAConformanceLevel

Optional.

Specifies the PDF/A conformance level. The supported levels are:

  • 1b
  • 1a
  • 2b
  • 2u
  • 2a
  • 3b
  • 3u
  • 3a

The default conformance level is 3a.

Only available when Processor=Rendition and ProducePDFA is set to true.

When Processor=Word, the conformance level is always 1b.

AccessibilityLevel Optional

Specifies the intended PDF/A accessibility level. The supported level is UA-1.

This level requires that the PDF/A conformance level has been set to 2a or 3a. It marks the document as being "UA-1"-compliant. DocToPDF checks a number of basic technical PDF/UA requirements and raises an error if these requirements are not met.

Due to complexity of the accessibility requirements, there is no guarantee that the specified accessibility level is completely met if the input document does not meet these requirements already.

Consider this setting as an enabler and use external means to validate the generated document and fix any remaining accessibility issues in the input document.

Only available when Processor=Rendition and ProducePDFA is set to true.

DPI Optional

The Rendition engine uses this setting when converting vector graphics to bitmaps and for rendering EMF/WMF graphics. Images included in the PDF file are not downsampled.

Outline Optional

Produces bookmarks in the PDF document representing the logical structure of the document.

If this parameter is omitted or empty, no bookmarks are produced.

If this parameter is set to "headings", heading styles are used to generate a nested bookmark structure.

If this parameter is set to "bookmarks", bookmarks in the document are used to generate the bookmarks as a flat list.

The default can be changed through the following setting in the dp.ini file: Rendition.Outline=<default>.

This parameter is introduced in KCM version 5.1.1.

Rendition-specific DocToPDF syntax: 

DocToPDF
   Src(<text>)
   Dest(<text>)
   TimeOut(<text>)
   ProducePDFA (True or False)
   DPI (<number>)
   Processor("Word" or "Rendition")
   SubstitutionFont (<text>)
   DPI (<number>)
   Outline("", "bookmarks" or "headings")
   PDFAConformanceLevel("1b", "1a", "2b", "2u", "2a", "3b", "3u", "3a")
   AccessibilityLevel("ua-1")

The defaults of the above parameters can be controlled in the dp.ini file as follows:

  • Rendition.Outline
  • Rendition.SubstitutionFont
  • Rendition.PDFAConformanceLevel
  • Rendition.AccessibilityLevel
  • DocToPDF.DPI

Additionally, the behavior of the Rendition engine can be controlled with the following global settings in the dp.ini file. These settings are not supported by the Word engine.

Parameter Description
Rendition.IgnoreUnsupportedContent

Set to N to have DocToPDF reject documents that contain content known to be unsupported. By default, the Rendition engine silently ignores unsupported content.

If not set, it defaults to Y.

Rendition.IgnoreUnsupportedContent=<Y or N>

Clearing this flag does not guarantee that the produced PDF documents are the same as the output produced by Microsoft Word. It flags a number of known issues.

Rendition.StrictParameterCheck

Set to Y to have the DocToPDF command report an error when it encounters an unsupported parameter or setting if Processor is set to Rendition.

If not set, it defaults to N.

Rendition.StrictParameterCheck=<Y or N>

The following parameters are ignored even when this setting is enabled:

  • ContentCompression
  • AutoImageCompression
  • CCITTCompression

Fonts used with Rendition

DocToPDF requires that all fonts that are used in a document are present on the system that performs the conversion. For documents that are composed by KCM and that need to be converted to PDF, we advise that all fonts that are used in the document templates are also installed on the system that does the conversion to PDF.

For documents that are not composed by KCM, we suggest specifying a substitution font that will be used instead of the fonts that are not present on the system. If neither the original font, not the substitution font can be found, DocToPDF will raise an error. If such an error occurs, make sure that at least the substitution font is installed.

Most fonts do not contain definitions for all possible unicode characters. If DocToPDF cannot find a font definition for a particular character in the original font, it will raise an error. Substitution font does not replace characters if the original font does not have the corresponding definitions.

Producing PDF/A with Rendition

A PDF/A document is a normal PDF document that adheres to certain restrictions and must include certain features, depending on the specified conformance level and accessibility level. For details, refer to information provided by Adobe and the PDF/UA foundation.

Unlike the Word Engine, the Rendition engine supports various PDF/A conformance levels, as well as the generation of PDF/UA documents. The specified conformance level and accessibility level may influence the graphical representation of the produced document or raise an error when the input document does not meet certain requirements, such as:

  • The 1b and 1a conformance levels do not allow transparency in the output. As a result the output may look slightly different. To resolve this, make sure that the input file does not contain graphical elements with transparency or use a higher conformance level.
  • Except for the 1b conformance level, all PDF/A output requires that a font definition is available for each character in the document. There are cases however that Word allows the use of a character code that does not have an entry in a symbolic font. In such a case, it is unknown what the character looks like. Word shows these characters as a rectangular box. DocToPDF does the same for the 1b conformance level, but for all other levels it raises an error. To fix this issue, make sure to only use characters that have a symbolic font definition. For non-symbolic fonts, find a suitable definition in a substitution font if the original font does not provide it.
  • The UA-1 accessibility level places additional technical requirements on the input document. All images must have an alternative text specified and headings must have proper nesting. Since Word does not enforce this, the PDF/A conversion checks these restrictions as much as possible and raises an error if they are not met.

DocToPDF cannot check all UA-1 requirements. For example, it does not check all restrictions on header nesting, nor whether colors with a high enough contrast have been used.

Note also that newer versions of Word may generate alternative text for inserted images automatically and it may be inappropriate or incorrect. It is necessary to inspect UA-1 conformance separately and correct the input document when needed. The PDF/UA foundation offers a free tool that helps validating PDF/A documents for UA-1 conformance.

Tagging features in PDF/A

The conformance levels of type 'a' tag the produced PDF/A document as follows:

  • Each paragraph is tagged with a 'P' tag.
  • Within a paragraph, inline tags are generated for links, images, graphical artifacts, and for spans that contain certain special characters.
  • Images are extended with the alternative text that has been set in the Word document (if any).
  • Heading tags of level H1 to H6 are generated for paragraphs that have the corresponding outline level set in Word. Level H6 is a maximum defined in the PDF/A standard for heading tags that specify a level. If the Word document uses headings with a deeper level, these are generated as a normal paragraph.
  • Table tags are generated for Word tables.
  • List tags are generated for Word lists, including proper nesting.
  • Headers and footers, including elements that are anchored in headers and footers, are tagged as artifacts, and are not taken into account for the main content.
  • The language of tagged text is set to the language as specified in Word.

Tagging limitations in PDF/A

The following limitations are present:

  • Paragraphs and Tables that span multiple pages are tagged as separate paragraphs and tables.
  • Table header cells are not recognized.
  • List labels are not recognized.
  • Special content like Table of Content entries and captions is not recognized.

Limitations of Rendition

The following features are currently not supported when converting DOCX files to PDF:

  • Objects with a transparent background. They get rendered with a white background.
  • Multiline borders when generating PDF/A. For non PDF/A documents, multiline borders are supported.
  • Pattern fills.
  • Linear gradient fills with an angle that is not a multiple of 45 degrees.
  • Radial gradients fills that do not have their center in the middle of the shaded area.
  • Graphical objects that are flipped (mirrored).
  • Shapes with 3D effects.
  • Charts. These are ignored completely.
  • Rendition provides limited EMF rendering support. We suggest that you avoid using this format.
  • Image-based bullets. Rendition only supports font-based bullets.

Rendition supports the following Word fields:

Value Description
DATE The Date field inserts the current date.

Example

10/23/2020
FILENAME

The FileName field inserts the file name of the document.

= (Formula)

The = (Formula) field code calculates a number by using a mathematical formula.

HYPERLINK A hyperlink allows you to move to another location.
IF The If field compares two values and then inserts the text appropriate to the result of the comparison.
NUMPAGES The NumPages field inserts the total number of pages in the document.
SECTIONPAGES The SectionPages field inserts the number of the current section.

Example

Page 4 of Section 2

PAGE The Page field inserts the number of the page that the Page field is located on.
PRINT The Print field sends printer-control code characters to the selected printer.
PRINTDATE The PrintDate field inserts the date and time that a document was last printed.

Example

10/22/2020 9:36:00 PM

QUOTE The Quote field inserts the specified text into a document.
REF The Ref field inserts the text or graphics represented by the specified bookmark.
TIME The Time field inserts the current time in your document.

Example

9:36 PM
TOC The TOC (Table of Contents) field builds a table of contents.