Documents

Handling and managing documents

Generating PDF output

The page describes the default mechanism for converting PSML documents to PDF and how to customize the formatting. 

Overview

XSL Formatting Objects (FO) is a companion standard to XML and XSLT. It's main design objectives are to provide developers with a standards-based language that can process raw XML data into visually rich output. With XSL FO, getting richly formatted pages from native XML is a relatively simple pipeline compared to using a proprietary typesetting solution or the transformation from XML into a more format-oriented syntax, such as TeX. 

By comparison, particularly for developers with XSLT experience, FO is a familiar, standards-based syntax supported by both open source and commercial implementations. To leverage the benefits of FO, PageSeeder comes pre-configured with Apache's FOP processor – a respected, open source FO processor. This capability enables PageSeeder to blindly export any PSML document as a PDF file.

The only problem with document formats being expressed in a programming language, is that developers are often not the best people to modify the formats. For this reason, the FO implementation in PageSeeder is accompanied by a simplified language FOConfig, that gives non-programmers some control over the page layout and liberates developers from being responsible for all changes.

The technical experience required to modify FO Config is much closer to working with Cascading Style Sheets (CSS) or a desktop publishing application.

Architecture

To generate a PDF document, the process uses the following components:

  • the FOConfig.xml file which defines the formatting values of the output;
  • a processor to generate XSL-FO code from the FOConfig.xml file and the PSML content.
  • the publish server passes the generated code to Apache FOP which returns the documents as PDF.

Structure

Structurally, the FOConfig.xml contains the following list of style elements, starting with a root of <styles>, and specialized by <property> elements: 

  • <page> – an element to contains that <property> elements that describes the page layout;
  • Region elements – a collection of predefined layout objects such as <header>, <footer> and <body>;
  • Block elements – formatting objects that correspond to the elements defined in PSML, including <heading, lists and so on;
  • Inline – these format the content contained by inline labels in PSML;
  • Special – various specialized elements.

Attached to each element can be multiple name / value pairs categorized as <property> or <region-property> elements. To make FO Config easy to learn and useful elsewhere, wherever possible, names and values are the same as XSL-FO.

Also supported are the following shorthand attributes which correspond to longer values:

  • background, background-position, border, border-bottom, border-color, border-left, border-right, border-style, border-spacing, border-top, border-width, font, margin, padding, page-break-after, page-break-before, page-break-inside, pause, position, vertical-align, white-space

By default PageSeeder uses the FOP 1.0 formatting engine. For more details about which properties are supported see Apache FOP Compliance Page .

For a copy of the default file, see FOConfig

<page> element

Used to define the page properties it corresponds to the XSL-FO simple-page-master element. Supported properties are:

  • page-width (defines the width of a page).
  • page-height (defines the height of a page).
  • margin-top
  • margin-bottom
  • margin-left
  • margin-right
  • space-before
  • space-after
  • start-indent
  • end-indent
  • reference-orientation

FOConfig:

<page>
  <property name="page-height"   value="29.7cm"/>
  <property name="page-width"    value="21cm"/>
  <property name="margin-top"    value="2cm"/>
  <property name="margin-bottom" value="2cm"/>
  <property name="margin-left"   value="2cm"/>
  <property name="margin-right"  value="2cm"/>
</page>

PDF:

The distance between the top of the page and the top of the header.

<page><property name="margin-top" value="2cm"/>

The distance between the right side of the page and the right boundary of the body text.

<page><property name="margin-right" value="2cm"/>

The distance between the bottom of the header and the top of the body text.

<body><region-property name="margin-top" value="1cm"/>

The distance between the left side of the page and the left boundary of the body text.

<page><property name="margin-left" value="2cm"/>

The full height of the page.

<page><property name="page-height" value="29.7cm"/>

The full width of the page.

<page><property name="page-width" value="21cm"/>

The distance between the bottom of the body text and the top of the footer.

<body><region-property name="margin-bottom" value="2cm"/>

The distance between the bottom of the footer and the bottom of the page.

<page><property name="margin-bottom" value="2cm"/>

Region Elements

These are the components that equate to what are often called master pages in conventional desktop applications.

<body>

Used to define the area that contains the document content. On these elements it is valid to use a property that corresponds to the XSL FO <region-body> element.

On the <body> element it is valid to use either or both a normal <property> and a <region-property>. In addition to the common values (except @extent), the following are valid attributes on a <region-property>:

  • @margin-top
  • @margin-bottom
  • @margin-left
  • @margin-right
  • @space-before
  • @space-after
  • @start-indent
  • @end-indent
  • @column-count
  • @column-gap

Also supported on <property> are the attribute "values" that that correspond to a nested XSL FO <block> element.

Example:

<body>
 <region-property name="margin-top"        value="1cm"/>
 <region-property name="margin-bottom"     value="2cm"/>
 <property name="font-family"              value="Times Roman"/>
</body>

 

<header> and <footer>

Used to define the page headers and footers and correspond to the XSL FO <region-before> and <region-after> elements.

Two types of property elements are allowed in a <body> element: normal <property> and <region-property>.

In addition to the common supported attributes, except @extent, the @precedence attribute is supported on <region-property>. Property values for a block are supported as normal and correspond to a nested XSL FO <block> element.

Configuring different headers and footers for first page and even/odd pages are defined by the attributes @first (allowed values are 'true' and 'false') and @odd-or-even (allowed values are 'odd' and 'even').

Headers and footers are composed of three customizable regions represented by the following elements:

  • <left>
  • <center>
  • <right>

Each of these elements can have a @width attribute and can contain elements which translate to specific fields. Allowed elements are:

  • <property> (any block property)
  • <text>
  • <image> (attribute @src is used to define the location of the graphic)
  • <date> (attribute @pattern can be used to define the output, see below)
  • <page-number>
  • <total-pages>
  • <filename>
  • <label> (attribute @name is used to specify the inline label, see below)

The <label> element is how to support dynamic headings/footers. Where specified in the FOConfig, in the PDF output, the <label> element will be replaced by the value of the content from the PSML  inline label of the same name. For example, if the document content was something like the following:

text <inline name="CompanyName">General Motors</inline> text

FOConfig:

<header first="true">
  <center width="500px"><label name="CompanyName" /></center>
</header>
<header>
  <property name="extent"        value="1cm" />
  <property name="line-height"   value="12pt"/>
  <property name="font-size"     value="10pt"/>
  <property name="border-bottom-style"   value="solid"/>
  <property name="border-bottom-width"   value="0.2mm"/>
  <left width="250px"><date pattern="[D1o] [MNn], [Y]" /></left>
</header>
<footer odd-or-even="odd">
  <property name="extent"        value="1cm" />
  <property name="font-size"     value="10pt"/>
  <left><text>Page <page-number/> of <total-pages/></text></left>
  <right><filename /></right>
</footer>
<footer odd-or-even="even">
  <property name="extent"        value="1cm" />
  <property name="font-size"     value="10pt"/>
  <left><filename /></left>
  <right><text>Page <page-number/> of <total-pages/></text></right>
</footer>

Until an instance of this inline label occurs, that value in the header will remain empty, however, each time the value changes in the content, it will be reflected in the next new page of the PDF output.

PDF:

The first page has a specific header which only contains text in its center. The content is taken from the first @inlineLabelName with a value of "CompanyName".

<header first="true"><center width="500px"><label name="CompanyName" />

Can specify Odd or Even within <header> element. If not specified, both odd and even pages will contain the same data. This right field contains the filename i.e. <header><right><filename/></right>

<header><right>

in this case is blank.

<header><center>

the left header field contains the date and its width will be 250px.

<header><left width="250px"><date pattern="[D1o] [MNn], [Y]" /></left>

the border is specified as below the header line, as a solid line of 0.2mm width.

<header><property name="border-bottom-style" value="solid"/>
<header><property name="border-bottom-width" value="0.2mm"/>

the footer is specified centered text containing the page number and total pages.

<footer><center><text>Page <page-number/> of <total-pages/></text></left>

<left> and <right>

Used to define left and right marginalia and correspond to the XSL FO region-start and region-end elements.

There are two types of properties allowed: region properties and normal properties.

All Common Region Properties are supported.

All Block Properties are supported as normal properties and correspond to a nested XSL FO block element.

These elements work the same as the <header> and <footer> elements. The main difference is that their content is defined using the three following elements:

  • <top>
  • <middle>
  • <bottom>

These elements work the same as the children elements of the header/footer elements (<left>, <center> and <right>).

Example:

<right first="true">
  <region-property name="extent"          value="60px" />
  <property name="font-size"              value="10pt"/>
  <top>
    <property name="border-left-style"    value="solid"/>
    <property name="border-left-width"    value="1mm"/>
    <text>top</text>
  </top>
  <middle height="100px">
    <text>middle</text>
  </middle>
  <bottom>
    <property name="border-left-style"    value="solid"/>
    <property name="border-left-width"    value="1mm"/>
    <text>bottom</text>
  </bottom>
</right>

Common Region Properties

Below are the region properties supported by all the above region elements.

  • Common Border, Padding, and Background Properties: background-color, background-image, background-repeat, background-position-horizontal, background-position-vertical, border-before-color, border-before-style, border-before-width, border-after-color, border-after-style, border-after-width, border-start-color, border-start-style, border-start-width, border-end-color, border-end-style, border-end-width, border-top-color, border-top-style, border-top-width, border-bottom-color, border-bottom-style, border-bottom-width, border-left-color, border-left-style, border-left-width, border-right-color, border-right-style, border-right-width, padding-before, padding-after, padding-start, padding-end, padding-top, padding-bottom, padding-left, padding-right.
  • Other: display-align, extent, overflow, reference-orientation, writing-mode.

Block Elements

Block elements are all defined by the attribute name on the tag element. The styling of the following block elements can be defined:

  • <blockXref>
  • <code>
  • <title>
  • <section-title>
  • <section-title2>
  • <toc> (table of contents)
  • <toc-title>
  • <cell>
  • <hcell>
  • <heading1>
  • <heading2>
  • <heading3>
  • <heading4>
  • <heading5>
  • <heading6>
  • <para>
  • <list>
  • <nlist>
  • <list-item>
  • <paraLabel>

Block Properties

  • Common Border, Padding, and Background Properties: background-color, background-image, background-repeat, background-position-horizontal, background-position-vertical, border-before-color, border-before-style, border-before-width, border-after-color, border-after-style, border-after-width, border-start-color, border-start-style, border-start-width, border-end-color, border-end-style, border-end-width, border-top-color, border-top-style, border-top-width, border-bottom-color, border-bottom-style, border-bottom-width, border-left-color, border-left-style, border-left-width, border-right-color, border-right-style, border-right-width, padding-before, padding-after, padding-start, padding-end, padding-top, padding-bottom, padding-left, padding-right.
  • Common Font Properties: font-family, font-size, font-stretch, font-size-adjust, font-style, font-variant, font-weight.
  • Common Hyphenation Properties: country, language, hyphenate, hyphenation-character, hyphenation-push-character-count, hyphenation-remain-character-count.
  • Common Margin Properties - Block: margin-top, margin-bottom, margin-left, margin-right, space-before, space-after, start-indent, end-indent.
  • Other: break-after, break-before, color, hyphenation-ladder-count, keep-together, keep-with-next, keep-with-previous, last-line-end-indent, linefeed-treatment, line-height, line-height-shift-adjustment, line-stacking-strategy, orphans, white-space-treatment, span, text-align, text-align-last, text-indent, white-space-collapse, widows, wrap-option.

Example:

<element name="heading1">
  <property name="font-weight"   value="bold"/>
  <property name="font-size"     value="20pt"/>
  <property name="space-before.optimum"  value="12pt"/>
  <property name="space-after.optimum"   value="12pt"/>
</element>

Document title and the next two hierarchically descending level of titles

<element name="title">PageSeeder FO Config</element>
<element name="section-title">not shown</element>
<element name="section-title2">not shown</element>

Heading level 1

<element name="heading1">Overview</element>

A paragraph

<element name="para">This file...</element>

Heading level 2

<element name="heading2">Page</element>

A list with three <list-items>

<element name="list"></element>

An container for code text

<element name="code"></element>

Inline Elements

Inline elements are all defined by the attribute name on the tag element. The styling of the following inline elements can be defined:

  • <bold>
  • <graphic>
  • <inlineLabel>
  • <italic>
  • <link>
  • <monospace>
  • <sub>
  • <sup>
  • <underline>
  • <xref>

Inline Properties

  • Common Border, Padding, and Background Properties: background-color, background-image, background-repeat, background-position-horizontal, background-position-vertical, border-before-color, border-before-style, border-before-width, border-after-color, border-after-style, border-after-width, border-start-color, border-start-style, border-start-width, border-end-color, border-end-style, border-end-width, border-top-color, border-top-style, border-top-width, border-bottom-color, border-bottom-style, border-bottom-width, border-left-color, border-left-style, border-left-width, border-right-color, border-right-style, border-right-width, padding-before, padding-after, padding-start, padding-end, padding-top, padding-bottom, padding-left, padding-right.
  • Common Font Properties: font-family, font-size, font-stretch, font-size-adjust, font-style, font-variant, font-weight.
  • Other: alignment-adjust, alignment-baseline, baseline-shift, block-progression-dimension, dominant-baseline, height, inline-progression-dimension, line-height, text-decoration, width, color, keep-together, keep-with-next, keep-with-previous,  wrap-option.

Special Elements

table-cell, table-hcell

Used to define table cells. A <table-cell​> with a @role attribute will specialize <cell> and <hcell> elements that have the same @role attribute.

Examples:

  <element name="table-hcell">
    <property name="background-color"       value="#1f4f76"/>   
  </element>

  <element name="table-cell">
    <property name="background-color"       value="#e7f1ff"/>   
  </element>

  <element name="table-cell" role="warning">
    <property name="background-color"       value="red"/>
  </element>

  <element name="cell" role="warning">
    <property name="font-size"              value="10pt"/>
  </element>

The following properties are supported:

  • Common Border, Padding, and Background Properties: background-color, background-image, background-repeat, background-position-horizontal, background-position-vertical, border-before-color, border-before-style, border-before-width, border-after-color, border-after-style, border-after-width, border-start-color, border-start-style, border-start-width, border-end-color, border-end-style, border-end-width, border-top-color, border-top-style, border-top-width, border-bottom-color, border-bottom-style, border-bottom-width, border-left-color, border-left-style, border-left-width, border-right-color, border-right-style, border-right-width, padding-before, padding-after, padding-start, padding-end, padding-top, padding-bottom, padding-left, padding-right.
  • Other: block-progression-dimension, inline-progression-dimension, height, width.

table

Used to define table level properties. It can have a @role attribute which will add specific properties to <table> elements that have the same @role attribute (role="pslabelvalues" is a special role applying to <section ... format="pslabelvalues"> which is displayed as a table in PDF).

Examples:

  <element name="table">
    <property name="space-before.optimum"   value="12pt"/>
    <property name="space-after.optimum"    value="12pt"/>
  </element

  <element name="table" role="warning">
    <property name="border-color"   value="red"/>
  </element>

In addition to the table-cell properties above the following properties are also supported:

  • Common Margin Properties - Block – margin-top, margin-bottom, margin-left, margin-right, space-before, space-after, start-indent, end-indent.
  • Other – border-collapse, border-separation, break-after, break-before, keep-together, keep-with-next, keep-with-previous, table-omit-footer-at-break, table-omit-header-at-break.

paraLabel

Used to define custom content Label.

Default properties are as follows:

    <element name="paraLabel">
        <property name="space-before.optimum"   value="4pt"/>
        <property name="space-after.optimum"    value="8pt"/>
        <property name="text-align"             value="justify"/>
        <property name="hyphenate"              value="false"/>
        <property name="border-top-style"       value="dotted"/>
        <property name="border-bottom-style"    value="dotted"/>
        <property name="border-left-style"      value="solid"/>
        <property name="border-right-style"     value="solid"/>
        <property name="border-width"           value="0.2mm"/>
        <property name="border-color"           value="#79bbe1"/>
        <property name="padding"                value="4px"/>       
    </element>
    <element name="paraLabelName">
        <property name="text-align"             value="justify"/>
        <property name="hyphenate"              value="false"/>
        <property name="color"                  value="#79bbe1"/>
        <property name="font-weight"            value="bold"/>      
    </element>

For each custom paraLabel, new properties can be specified to overwrite the default properties in FOConfig.xml. Simply create a new element name ="paraLabel-[customname]" and "paraLabelName-[customname]" accordingly with the desired property.

Example:

  <element name="paraLabel-warning">
      <property name="color"                  value="red"/>
      <property name="border-top-style"       value=""/>
      <property name="border-bottom-style"    value=""/>
      <property name="border-left-style"      value=""/>
      <property name="border-right-style"     value=""/>
      <property name="border-width"           value=""/>
      <property name="border-color"           value=""/>
  </element>
  <element name="paraLabelName-warning">
      <property name="ps-hide"             value="true"/>
  </element>

The above definition will remove the standard label border and display, in red, the paraLabel named 'warning'. NOTE the special PageSeeder property ps-hide=true will stop the label name from appearing.

inlineLabel

Used to define custom inline content Label.

Default properties are as follows:

    <element name="inlineLabel">
        <property name="hyphenate"              value="false"/>
        <property name="padding-right"          value="2px"/>
        <property name="background-color"       value="#DD9999"/>
    </element>
    
    <element name="inlineLabelName">
        <property name="text-align"             value="justify"/>
        <property name="hyphenate"              value="false"/>
        <property name="color"                  value="#AA4444"/>
        <property name="font-weight"            value="bold"/>
        <property name="background-color"       value="#DD9999"/>
        <property name="padding-left"           value="2px"/>
        <property name="padding-right"          value="2px"/>
        <property name="margin-right"           value="2px"/>
    </element>

For each custom inlineLabel, new properties can be specified to overwrite the default properties in FOConfig.xml. Simply create a new element name ="inlineLabel-[customname]" and "inlineLabelName-[customname]" and insert the customized properties.

Example:

  <element name="inlineLabel-drug">
      <property name="font-style"   value="italic"/>
      <property name="padding-right"          value=""/>
      <property name="background-color"       value=""/>
  </element>
 
  <element name="inlineLabelName-drug">
      <property name="ps-hide"             value="true"/>
  </element>

 The above definition will remove the standard label border and display, in italic, the inlineLabel named 'drug'. NOTE the special PageSeeder property ps-hide=true will stop the label name from appearing.

body type

Used to define body type styles. There are no default properties.

For each body type specified in your section templates, properties can be specified. Simply create a new <element name ="body-[type]">.

Example:

  <element name="body-chapter">
    <property name="break-before"           value="page"/>
  </element> 

The above definition will put a page break before fragments with <body
type="chapter">

Table of contents elements

Elements from the table of contents can be formatted in the final document by using specific names. Each line in the table of contents is defined by a level and it is the name used for the element, with the "ps" prefix (i.e.: ps:level1, ps:level2...).

The special property called ps-hide (which can be used for labels, see above) can be used here to not display certain levels. For example to make level 4 red and hide levels 5 and 6 in the table of contents, the following needs to be added to the configuration file:

<element name="ps:level4">
     <property name="margin-left"        value="80px"/>
     <property name="text-align-last"    value="justify"/>
     <property name="color"              value="red"/>
</element>

<element name="ps:level5">
     <property name="ps-hide" value="true"/>
</element>

<element name="ps:level6">
     <property name="ps-hide" value="true"/>
</element>

Date Pattern

The <date> element is used to specify that the current date should be inserted at a special location in a header or footer. The attribute @pattern can be used to describe what the output date should look like. Its format uses the square brackets ([]) to insert a specific part of the date (month, day, year...) and the following key letters:

LetterMeaning
year
Mmonth in year
Dday in month
dday in year
Fday of week
Wweek in year
wweek in month
oordinal form
n, N or Nnuse name (lower-case, upper-case, title-case).

Here are some examples of date formats and the corresponding pattern:

Date formatPattern
2002-12-31[Y0001]-[M01]-[D01]
12-31-2002[M]-[D]-[Y]
31/12/2002[D]/[M]/[Y]
31st December, 2002[D1o] [MNn], [Y]
31 DEC 2002[D01] [MN,*-3] [Y0001]
December 31, 2002[MNn] [D], [Y]

The default pattern used (if none is specified) is [MNn] [D], [Y].

Example

<?xml version="1.0"?>
<styles>
    <!-- ===============GENERAL PROPERTIES================ -->
    <page>
        <property name="page-height"               value="29.7cm"/>
            <property name="page-width"            value="21cm"/>
            <property name="margin-top"        value="2cm"/>
            <property name="margin-bottom"     value="2cm"/>
            <property name="margin-left"           value="2cm"/>
            <property name="margin-right"      value="2cm"/>
    </page>
    <body>
            <property name="margin-top"        value="1cm"/>
            <property name="margin-bottom"     value="2cm"/>
            <property name="font-family"       value="Times Roman"/>
    </body>
    <header>
        <property name="extent"        value="1cm" />
        <property name="line-height"   value="12pt"/>
        <property name="font-size"     value="10pt"/>
        <property name="border-bottom-style"   value="solid"/>
        <property name="border-bottom-width"   value="0.2mm"/>
        <left><filename /></left>
        <right><date pattern="[D1o] [MNn], [Y]" /></right>
    </header>
    <footer>
        <property name="extent"        value="1cm" />
        <property name="font-size"     value="10pt"/>
        <center><text>Page <page-number/> of <total-pages/></text></center>
    </footer>

    <!-- ===============ELEMENTS PROPERTIES=============== -->

    <element name="section-title">
        <property name="font-weight"   value="bold"/>
        <property name="font-size"     value="20pt"/>
    </element>

    <element name="toc">
        <property name="space-before.optimum"  value="10pt"/>
        <property name="space-after.optimum"   value="10pt"/>
    </element>

    <element name="toc-title">
        <property name="font-weight"   value="20pt"/>
        <property name="space-before.optimum"  value="12pt"/>
        <property name="space-after.optimum"   value="12pt"/>
    </element>

    <element name="table">
        <property name="space-before.optimum"  value="12pt"/>
        <property name="space-after.optimum"   value="12pt"/>
    </element>

    <element name="heading1">
        <property name="font-weight"   value="bold"/>
        <property name="font-size"     value="22pt"/>
        <property name="space-before.optimum"  value="12pt"/>
        <property name="space-after.optimum"   value="12pt"/>
    </element>

    <element name="heading2">
        <property name="font-size"     value="20pt"/>
    </element>

    <element name="heading3">
        <property name="font-weight"   value="bold"/>
        <property name="font-size"     value="18pt"/>
    </element>

    <element name="para">
        <property name="space-before.optimum"  value="5pt"/>
        <property name="space-after.optimum"   value="5pt"/>
        <property name="text-align"        value="justify"/>
    </element>

    <element name="link">
        <property name="color"     value="orange"/>
    </element>

</styles>

Created on , last edited on