PDF output reference for designing templates

Review this information to learn more about generating PDF documents with the Rational® Publishing Engine PDF driver.

Purpose

To output the template into a .pdf document.

Supported content viewers

For a list of products that are supported for viewing this output type:
  1. Open the System Requirements for Rational Publishing Engine.
  2. In the By type section, click Software.
  3. Scroll to the Content viewers section. Product names and versions that are supported for viewing Rational Publishing Engine output are listed.

Choosing between the PDF drivers

The default PDF driver produces version 1.5 PDF files. You can still choose to use the Legacy PDF driver, which produces version 1.4 PDF files.

If you create a document specification in Rational Publishing Engine 1.1.2.1 or earlier and open it with Rational Publishing Engine 1.1.2.2 or later, the PDF settings are migrated to the later version PDF and Legacy PDF settings. If you create a document specification in Rational Publishing Engine 1.1.2.2 or later and open it with Rational Publishing Engine 1.1.2.1 or earlier, the Legacy PDF driver is used by default. If both the PDF and Legacy PDF drivers were configured in the version 1.1.2.2 or later document specification, two PDF driver instances are created and are the same. If this duplication occurs, you can delete the duplicate driver from the document specification.

Template elements

Table 1. Template elements available to use for the PDF output format
Element Description Can contain other elements Can contain data
Paragraph icon Paragraph Use to group a section of elements. Adds a carriage return around its child elements in the output. Yes No
Container icon Container Use to group a section of elements. Cannot be styled and does not affect the formatting of the output.
When used inside other elements, the child elements available to use within the container might be limited. For example:
  • Inside rows, containers can host cells only
  • Inside lists, containers can host list-detail elements only
Yes No
Text icon Text The content renders with the same, specified formatting. No Yes
Styled text icon Styled text A block of text that can have unique formatting on individual words. Use bold, italic, underline, strikeout, or color formatting on a selection of words within the element. The text is static. No Yes
Hyperlink icon Hyperlink Creates a hyperlink in the output. The hyperlink can point to a location inside the document or to an external location. No Yes
Image icon Image Displays a .gif, .png, .jpg, emf, or wmf image in the output. The report designer can specify the image path in the template or the report generator can specify the path at run time. No Yes
Table icon Table Creates a table in the output. A table can contain rows or container elements. Yes No
Row icon Row Creates a row in the current table. Yes No
Cell icon Cell Creates a cell in the current row of the current table. Yes No
List icon List Creates a bulleted or numeric list in the output. Yes No
List detail icon List detail Creates a list item in the current list in the output. Yes No
Data Source configuration icon Data source configuration See Adding a data source configuration element. No No
Include file icon Include file Includes the specified file in the output as an INCLUDETEXT field.
  • Included file can have a .doc, .docx, .txt, or .rtf extension.
  • For Microsoft Word output, you must update all fields with the macro to see the included file.
  • For Legacy PDF, HTML, and XSL-FO output, the included file is a hyperlink to the document.
No Yes
Region icon Region Regions are static elements that allow you to alter the output flow by redirecting the content of other elements or groups of elements. If an element has the target region property specified with the name of a region element, its content renders in the specified region instead of in its position in the document. No No
Bookmark icon Bookmark Defines a bookmark in the document. The name of the generated bookmark is the content for the bookmark. When generating the documents, Rational Publishing Engine generates a unique name for each bookmark. The name is based on the name provided at design time and a unique identifier generated at run time. No Yes
Page Break icon Page Break Adds a page break to the output. No No
Section Break icon Section Break Adds a section break to the output. No No
Table of Contents icon Table of Contents Adds a table of contents to the output. No No
Page Number icon Page Number Adds a page number in the output. Supported in Microsoft Word and PDF output only. No No
Total Pages Number icon Total Pages Number Adds the total number of pages in the output. Supported for Microsoft Word and PDF output only. No No

If the PDF is slow to generate, add Section break element icon Section break elements to the template to improve performance.

Element properties

Review these notes to understand more about specifying the element properties in templates that are designed to generate PDF documents.
Table 2. Cell properties
Cell properties Notes®
Border width You must specify a border width value between 1 and 30 pixels to create a border in the output.
Cell alignment This property specifies the position of the text within the cell. The justify value is not supported for this output format.
Cell width Enter a value in points or pixels. If you enter a value in pixels, the value is converted to points and assumes that the display is 96 dpi. If you enter a value as a percentage, the value is ignored. When you are combining tables, you must set the cell width property to ensure that the column sizes are the same.
Col span All rows and columns must contain the same number of cells. The borders between cells are removed, but only the content or properties specified for the first cell are applied to the output. Avoid overlapping spans.
Row span All rows and columns must contain the same number of cells. The borders between cells are removed, but only the content or properties specified for the first cell are applied to the output. Avoid overlapping spans.
Table 3. Comment properties
Comment properties Notes
Content If you include hyperlinks in the Content property of Comment elements, the hyperlinks are clickable in the PDF output.
Table 4. Figure caption properties
Figure caption properties Notes
Border width Do not use for this output format.
Field code Arabic or Roman numerals display sequentially on each caption.
Table 5. Footnote properties
Footnote properties Notes
Style name If you apply a style to inline elements such as footnotes, text, styled text, or tables, the style is applied to all of the inline elements until the next block element, such as a paragraph. For example, if you add a style to a footnote element and there is a styled text element before it, the style is also applied to the styled text element.
Table 6. Image properties
Image properties Notes
Border width Do not use for this output format.
Content Supported image formats: .bmp, .emf, .gif, .jpg, .png, .wmf

.svg images are supported by Rational Publishing Engine, but are not supported by Microsoft Word. The PDF driver uses functionality from Microsoft Word. To generate the document correctly into PDF output, .svg images are converted to .png images. The conversion process can distort the display of the image in the output.

Table 7. List properties
List properties Notes
Numbering style You can use the following styles:
  • Bullet: Unordered lists
  • Arabic: Numbered lists
  • Uppercase roman: Uppercase roman numerals
  • Lowercase roman: Lowercase roman numerals
  • Uppercase alpha: Uppercase letters
  • Lowercase alpha: Lowercase letters
Numbering character spacing Do not use for this output format.
Table 8. List-detail properties
List-detail properties Notes
Border width Do not use for this output format.
Table 9. Page number properties
Page number properties Notes
Border width Do not use for this output format.
Table 10. Paragraph properties
Paragraph properties Notes
Border width You must specify a border width value between 1 and 30 pixels to create a border in the output.
Paragraph alignment Space the text across the page with a certain alignment.

Left, right, and center alignment, creates uneven paragraph edges, fitting as many words in a paragraph as possible. Justify creates even paragraph edges by inserting additional space between words on all lines except the last line.

Do not use distributed for this output format.

Widow/orphan control When set to true, the line spacing is adjusted to prevent the following formatting results:
  • A single word ending a paragraph on a new line
  • A single line ending a paragraph on a new page

When set to false, spacing is not adjusted.

Table 11. Row properties
Row properties Notes
Row break across pages When set to true, the content of a row that comes at the end of a page is split, if necessary. The content that does not fit on the page carries over onto the next page as a new row.

When set to false, the content of a row that comes at the end of the page is not split. The whole row carries over onto the next page.

Table 12. Styled text properties
Styled text properties Notes
Style name If you apply a style to inline elements such as footnotes, text, styled text, or tables, the style is applied to all of the inline elements until the next block element, such as a paragraph. For example, if you add a style to a footnote element and there is a styled text element before it, the style is also applied to the styled text element.
Table 13. Table properties
Table properties Notes
Autofit to contents Resizes the table to fit the content each cell contains. When you use this property, also set the Resize to fit contents property to true.
Autofit to window Resizes the table to the page width. Clear this property when Resize to fit contents is false.
Border width You must specify a border width value between 1 and 30 pixels to create a border in the output.
Border style Use the value single instead of thick, hairline, inset, or outset. The same formatting is applied for all of these values and most closely resembles what you would expect to see for single.
Cell spacing Do not use for this output format.
Fixed cell width in column Specify a value in pixels to ensure that all of the cells in a column are the same width.
Resize to fit contents When the value is true, and the width and autofit to window are cleared, the column width is adjusted to fit the content. If autofit to contents is set, you must set resize to fit contents to true.

When the value is false, clear the width and autofit to window properties for the table. The table is generated with the default column size of one inch.

Style name If you apply a style to inline elements such as footnotes, text, styled text, or tables, the style is applied to all of the inline elements until the next block element, such as a paragraph. For example, if you add a style to a footnote element and there is a styled text element before it, the style is also applied to the styled text element.
Table auto fit When set to true, the table is resized to fit the width of the page. When resize to fit contents is also set to true, cell widths are ignored and the table is resized to match the content.

You cannot enter fixed column width as a value. Use the fixed cell width property instead.

Width You must specify a value unless you set the Resize to fit contents property to false.
Table 14. Table caption properties
Table caption properties Notes
Border width Do not use for this output format.
Field code Arabic or Roman numerals display sequentially on each caption.
Table 15. Text properties
Text properties Notes
Border width You must specify a border width value between 1 and 30 pixels to create a border in the output.
Style name If you apply a style to inline elements such as footnotes, text, styled text, or tables, the style is applied to all of the inline elements until the next block element, such as a paragraph. For example, if you add a style to a footnote element and there is a styled text element before it, the style is also applied to the styled text element.
Table 16. Total pages number properties
Total pages number properties Notes
Border width Do not use for this output format.

Include file element

You can choose to link the file or physically embed the file into your output document. However, the way that include file elements are handled depends on the output format and the location from which you are retrieving the file. For PDF output, the included file is imported and the full contents of the document display.

Heading styles

PDF output formats do not have heading styles; however, Rational Publishing Engine uses internally defined heading styles.

Unicode data in output

All Unicode data is rendered if the font that is used supports Unicode. For PDF output, additional configuration is necessary. See the PDF output settings for details. If you used a non-Unicode font, generate the document again using True Type Unicode fonts and set the appropriate output properties.

OLE objects

You can extract embedded objects, such as Object linking and embedding (OLE objects), from attributes in a data source. OLE objects are always rendered as images in PDF output though, because the format does not support OLE objects.

Feedback