XEP User Guide/Appendix A XSL-FO Conformance

From Docs

Jump to: navigation, search

Get PDF

Contents

XSL-FO Support

This appendix describes the implementation of XSL Formatting Objects in XEP — an XSL Engine for PDF developed by RenderX, Inc, version 4.13. It lists all supported formatting objects and their properties, provides information about fallbacks for unsupported objects and discusses details of interpretation of XSL specifications adopted in the engine.

Note: XEP implements Extensible Stylesheet Language version 1.0 as specified in the XSL 1.0 Recommendation of October 15, 2001 .

Formatting Objects Supported by XEP

§ Object Name Supported
6.4.2 <fo:root> Yes
6.4.3 <fo:declarations> No
6.4.4 <fo:color-profile> No
6.4.5 <fo:page-sequence> Yes
6.4.6 <fo:layout-master-set> Yes
6.4.7 <fo:page-sequence-master> Yes
6.4.8 <fo:single-page-master-reference> Yes
6.4.9 <fo:repeatable-page-master-reference> Yes
6.4.10 <fo:repeatable-page-master-alternatives> Yes
6.4.11 <fo:conditional-page-master-reference> Yes
6.4.12 <fo:simple-page-master> Yes
6.4.13 <fo:region-body> Yes
6.4.14 <fo:region-before> Yes
6.4.15 <fo:region-after> Yes
6.4.16 <fo:region-start> Yes
6.4.17 <fo:region-end> Yes
6.4.18 <fo:flow> Yes
6.4.19 <fo:static-content> Yes
6.4.20 <fo:title> No
6.5.2 <fo:block> Yes
6.5.3 <fo:block-container> Yes
6.6.2 <fo:bidi-override> Yes
6.6.3 <fo:character> Yes
6.6.4 <fo:initial-property-set> Yes
6.6.5 <fo:external-graphic> Yes
6.6.6 <fo:instream-foreign-object> Yes [1]
6.6.7 <fo:inline> Yes
6.6.8 <fo:inline-container> No [2]
6.6.9 <fo:leader> Yes [3]
6.6.10 <fo:page-number> Yes
6.6.11 <fo:page-number-citation> Yes
6.7.2 <fo:table-and-caption> Yes
6.7.3 <fo:table> Yes
6.7.4 <fo:table-column> Yes
6.7.5 <fo:table-caption> Yes
6.7.6 <fo:table-header> Yes
6.7.7 <fo:table-footer> Yes
6.7.8 <fo:table-body> Yes
6.7.9 <fo:table-row> Yes
6.7.10 <fo:table-cell> Yes
6.8.2 <fo:list-block> Yes
6.8.3 <fo:list-item> Yes
6.8.4 <fo:list-item-body> Yes
6.8.5 <fo:list-item-label> Yes
6.9.2 <fo:basic-link> Yes
6.9.3 <fo:multi-switch> -
6.9.4 <fo:multi-case> -
6.9.5 <fo:multi-toggle> -
6.9.6 <fo:multi-properties> -
6.9.7 <fo:multi-property-set> -
6.10.2 <fo:float> Yes [4]
6.10.3 <fo:footnote> Yes
6.10.4 <fo:footnote-body> Yes
6.11.2 <fo:wrapper> Yes
6.11.3 <fo:marker> Yes [5]
6.11.4 <fo:retrieve-marker> Yes


Formatting Properties Supported by XEP

§ Property Name Implemented
7.4.1 source-document No
7.4.2 role No
7.5.1 absolute-position Yes [6]
7.5.2 top Yes
7.5.3 right Yes
7.5.4 bottom Yes
7.5.5 left Yes
7.6.1 azimuth -
7.6.2 cue-after -
7.6.3 cue-before -
7.6.4 elevation -
7.6.5 pause-after -
7.6.6 pause-before -
7.6.7 pitch -
7.6.8 pitch-range -
7.6.9 play-during -
7.6.10 richness -
7.6.11 speak -
7.6.12 speak-header -
7.6.13 speak-numeral -
7.6.14 speak-punctuation -
7.6.15 speech-rate -
7.6.16 stress -
7.6.17 voice-family -
7.6.18 volume -
7.7.1 background-attachment Yes
7.7.2 background-color Yes
7.7.3 background-image Yes
7.7.4 background-repeat Yes
7.7.5 background-position-horizontal Yes [7]
7.7.6 background-position-vertical Yes [7]
7.7.7 border-before-color Yes
7.7.8 border-before-style Yes
7.7.9 border-before-width Yes
7.7.10 border-after-color Yes
7.7.11 border-after-style Yes
7.7.12 border-after-width Yes
7.7.13 border-start-color Yes
7.7.14 border-start-style Yes
7.7.15 border-start-width Yes
7.7.16 border-end-color Yes
7.7.17 border-end-style Yes
7.7.18 border-end-width Yes
7.7.19 border-top-color Yes
7.7.20 border-top-style Yes
7.7.21 border-top-width Yes
7.7.22 border-bottom-color Yes
7.7.23 border-bottom-style Yes
7.7.24 border-bottom-width Yes
7.7.25 border-left-color Yes
7.7.26 border-left-style Yes
7.7.27 border-left-width Yes
7.7.28 border-right-color Yes
7.7.29 border-right-style Yes
7.7.30 border-right-width Yes
7.7.31 padding-before Yes
7.7.32 padding-after Yes
7.7.33 padding-start Yes
7.7.34 padding-end Yes
7.7.35 padding-top Yes
7.7.36 padding-bottom Yes
7.7.37 padding-left Yes
7.7.38 padding-right Yes
7.8.2 font-family Yes
7.8.3 font-selection-strategy Yes
7.8.4 font-size Yes
7.8.5 font-stretch Yes
7.8.6 font-size-adjust Yes
7.8.7 font-style Yes
7.8.8 font-variant No
7.8.9 font-weight Yes
7.9.1 country No
7.9.2 language Yes
7.9.3 script No
7.9.4 hyphenate Yes
7.9.5 hyphenation-character Yes
7.9.6 hyphenation-push-character-count Yes
7.9.7 hyphenation-remain-character-count Yes
7.10.1 margin-top Yes
7.10.2 margin-bottom Yes
7.10.3 margin-left Yes
7.10.4 margin-right Yes
7.10.5 space-before Yes
7.10.6 space-after Yes [8]
7.10.7 start-indent Yes
7.10.8 end-indent Yes
7.11.1 space-end Yes
7.11.2 space-start Yes
7.12.1 relative-position No
7.13.1 alignment-adjust Yes
7.13.2 alignment-baseline Yes
7.13.3 baseline-shift Yes
7.13.4 display-align Yes
7.13.5 dominant-baseline Yes
7.13.6 relative-align Yes [9]
7.14.1 block-progression-dimension Yes
7.14.2 content-height Yes
7.14.3 content-width Yes
7.14.4 height Yes
7.14.5 inline-progression-dimension Yes
7.14.6 max-height No [10]
7.14.7 max-width No [11]
7.14.8 min-height No [12]
7.14.9 min-width No [13]
7.14.10 scaling Yes
7.14.11 scaling-method No
7.14.12 width Yes
7.15.1 hyphenation-keep No
7.15.2 hyphenation-ladder-count No
7.15.3 last-line-end-indent Yes
7.15.4 line-height Yes
7.15.5 line-height-shift-adjustment Yes
7.15.6 line-stacking-strategy Yes
7.15.7 linefeed-treatment Yes [14]
7.15.8 white-space-treatment Yes
7.15.9 text-align Yes [15]
7.15.10 text-align-last Yes
7.15.11 text-indent Yes
7.15.12 white-space-collapse Yes [16]
7.15.13 wrap-option Yes
7.16.1 character Yes
7.16.2 letter-spacing Yes
7.16.3 suppress-at-line-break No
7.16.4 text-decoration Yes
7.16.5 text-shadow Yes [17]
7.16.6 text-transform Yes [18]
7.16.7 treat-as-word-space No
7.16.8 word-spacing Yes
7.17.1 color Yes
7.17.2 color-profile-name No
7.17.3 rendering-intent No
7.18.1 clear Yes
7.18.2 float Yes [19]
7.18.3 intrusion-displace Yes [20]
7.19.1 break-after Yes
7.19.2 break-before Yes
7.19.3 keep-together Yes [21]
7.19.4 keep-with-next Yes [21]
7.19.5 keep-with-previous Yes [21]
7.19.6 orphans Yes
7.19.7 widows Yes
7.20.1 clip No
7.20.2 overflow Yes [22]
7.20.3 reference-orientation Yes
7.20.4 span Yes
7.21.1 leader-alignment No
7.21.2 leader-pattern Yes
7.21.3 leader-pattern-width Yes
7.21.4 leader-length Yes
7.21.5 rule-style Yes
7.21.6 rule-thickness Yes
7.22.1 active-state -
7.22.2 auto-restore -
7.22.3 case-name -
7.22.4 case-title -
7.22.5 destination-placement-offset No
7.22.6 external-destination Yes [23]
7.22.7 indicate-destination No
7.22.8 internal-destination Yes
7.22.9 show-destination Yes [24]
7.22.10 starting-state -
7.22.11 switch-to -
7.22.12 target-presentation-context -
7.22.13 target-processing-context -
7.22.14 target-stylesheet -
7.23.1 marker-class-name Yes
7.23.2 retrieve-class-name Yes
7.23.3 retrieve-position Yes
7.23.4 retrieve-boundary Yes
7.24.1 format Yes
7.24.2 grouping-separator No
7.24.3 grouping-size No
7.24.4 letter-value No
7.25.1 blank-or-not-blank Yes
7.25.2 column-count Yes
7.25.3 column-gap Yes
7.25.4 extent Yes
7.25.5 flow-name Yes
7.25.6 force-page-count Yes
7.25.7 initial-page-number Yes
7.25.8 master-name Yes
7.25.9 master-reference Yes
7.25.10 maximum-repeats Yes
7.25.11 media-usage No
7.25.12 odd-or-even Yes
7.25.13 page-height Yes
7.25.14 page-position Yes
7.25.15 page-width Yes
7.25.16 precedence Yes
7.25.17 region-name Yes
7.26.1 border-after-precedence Yes
7.26.2 border-before-precedence Yes
7.26.3 border-collapse Yes
7.26.4 border-end-precedence Yes
7.26.5 border-separation Yes
7.26.6 border-start-precedence Yes
7.26.7 caption-side Yes [25]
7.26.8 column-number Yes
7.26.9 column-width Yes
7.26.10 empty-cells No [26]
7.26.11 ends-row Yes
7.26.12 number-columns-repeated Yes
7.26.13 number-columns-spanned Yes
7.26.14 number-rows-spanned Yes
7.26.15 starts-row Yes
7.26.16 table-layout Yes
7.26.17 table-omit-footer-at-break Yes
7.26.18 table-omit-header-at-break Yes
7.27.1 direction Yes
7.27.2 glyph-orientation-horizontal No
7.27.3 glyph-orientation-vertical No
7.27.4 text-altitude Yes
7.27.5 text-depth Yes
7.27.6 unicode-bidi Yes [27]
7.27.7 writing-mode Yes [28]
7.28.1 content-type Yes
7.28.2 id Yes
7.28.3 provisional-label-separation Yes
7.28.4 provisional-distance-between-starts Yes
7.28.5 ref-id Yes
7.28.6 score-spaces No
7.28.7 src Yes [29]
7.28.8 visibility No
7.28.9 z-index Yes [30]
7.29.1 background Yes
7.29.2 background-position Yes
7.29.3 border Yes
7.29.4 border-bottom Yes
7.29.5 border-color Yes
7.29.6 border-left Yes
7.29.7 border-right Yes
7.29.8 border-style Yes
7.29.9 border-spacing Yes
7.29.10 border-top Yes
7.29.11 border-width Yes
7.29.12 cue -
7.29.13 font Yes
7.29.14 margin Yes
7.29.15 padding Yes
7.29.16 page-break-after Yes
7.29.17 page-break-before Yes
7.29.18 page-break-inside Yes
7.29.19 pause -
7.29.20 position Yes
7.29.21 size Yes
7.29.22 vertical-align Yes
7.29.23 white-space Yes
7.29.24 xml:lang No


Notes on Formatting Objects Implementation

<fo:block>  
According to the specification, an empty block that has a non-null padding and/or border should be visible. XEP suppresses all blocks that have no visible contents regardless of their border or padding attributes.
<fo:bidi-override>  
In the current implementation of bidi algorithm, any markup element opens a new level of embedding. Consequently, unicode-bidi = "normal" is not supported: <fo:bidi-override> behaves as if unicode-bidi = "embed" were specified.
<fo:inline-container>  
Unsupported; contents are placed inline.

<fo:multi-switch>

<fo:multi-case>

<fo:multi-toggle>

<fo:multi-properties>

<fo:multi-property-set>  
Unsupported; contents are ignored. These elements deal with interactivity. Since PDF and PostScript are intrinsically static formats, none of them are applicable.
<fo:float>  
The before-float appears at the top of the next page.
<fo:table-caption>  
Only "before" and "after" captions are implemented. Side captions are treated as follows: caption-side = "start" falls back to "before" , and caption-side = "end" falls back to "after."
<fo:table-footer>  
Table footer repetition is not implemented. The element is drawn once at the end of table.
<fo:table-column>  
In the collapsed border model, only border-start and border-end are supported on <fo:table-column> elements.
<fo:table-row>  
In the collapsed border model, only border-before and border-after are supported on <fo:table-row> elements.
<fo:table-cell>  
If a cell spans multiple rows in a table with a collapsed border model, its border-after is taken from the row where the cell begins.
<fo:leader>  
In this version, leaders with leader-pattern = "use-content" can only contain plain text inside; all formatting is lost.
<fo:marker>  
This version cannot process markers specified as children of an <fo:wrapper> .

Supported Expressions

XEP implements a subset of XSL algebraic expressions. The following operators and functions are recognized:

  • Arithmetical operators: + , - , * , div , mod
  • floor()
  • ceiling()
  • round()
  • abs()
  • max()
  • min()
  • rgb()
  • rgb-icc() (supported partially — see notes below)
  • from-nearest-specified-value()
  • from-parent()
  • from-table-column()
  • inherited-property-value()
  • proportional-column-width()
  • body-start() (standalone use only, cannot be an operand in expressions)
  • label-end() (standalone use only, cannot be an operand in expressions)

Function rgb-icc() recognizes four predefined color profile names: #Grayscale , #CMYK , #SpotColor , and #Registration (see details below). For any other value of the fourth parameter, the function returns the fallback RGB color. ICC profiles are not supported.

Support for expressions is subject to the following limitations:

  • For compound expressions, the result of evaluation of all intermediate subexpressions must be a valid XSL type. For example, expression (2in * 2in) div 1in is not supported because its first subexpression yields dimensionality of square inches, which is not a valid XSL unit; while 2in * (2in div 1in) works.
  • Expressions that require knowledge of layout to evaluate (e.g. Block widths expressed in percentages) can only be used as standalone expressions, not parts of a bigger expression, and cannot be referenced by property-value functions. The same limitation applies to body-start() and label-end() functions.
  • Property value functions ( from-nearest-specified-value() , from-parent() , from-table-column() , inherited-property-value() ) cannot be used in shorthands, and cannot take shorthand property names as their arguments.
  • Property value functions that take start-indent / end-indent as arguments may not work correctly if the block with indents is placed into another block that has CSS-style margin-* attributes. For safety, use either expressions with indents, or CSS margins; mixing these two coding styles in the same stylesheet may yield unpredictable results.

Color Specifiers

XEP can produce PDF and PostScript output using the following color types:

  1. Grayscale . The following specifiers produce grayscale color output:
    • Predefined HTML and SVG names that correspond to RGB values with R = G = B : white , black , silver , gray , grey , lightgray , lightgrey , darkgray , darkgrey , dimgray , dimgrey , whitesmoke , gainsboro.
    • HTML-style RGB values with R = G = B : #555 , #9D9D9D , etc.
    • rgb-icc() function with built-in #Grayscale pseudo profile. Gray tone intensity is specified as a real value in the range 0.01.0 , the 5th argument to the function. Example:
      rgb-icc (128, 128, 128, #Grayscale, 0.5)

  2. RGB . The following specifiers produce RGB color output:
    • HTML and SVG predefined names, and RGB specifiers that are not mentioned above.
    • rgb() function. Values of color components are specified as real values in the range 0.0255.0 . Example:
      rgb (127.5, 39.86, 255)
  3. CMYK . The following specifier produce CMYK color output:
    • rgb-icc() function with built-in #CMYK pseudo profile. Ink values are specified as real values in the range 0.01.0 , arguments from 5th to 8th; order of inks is cyanmagentayellowblack . Example:
      rgb-icc (255, 255, 0, #CMYK, 0, 0, 1, 0)
  4. Spot colors . The following specifiers produce spot color output:
    • rgb-icc() function with built-in #SpotColor pseudo profile. The 5th argument is the colorant name, specified as a string; use quotes if the name contains spaces. The 6th argument is the tint value, specified as a real number in the range 0.01.0 . These mandatory attributes may be followed by an optional specification of the alternate color for the colorant, in either CMYK or grayscale color space: 7th argument is the color space name (either #CMYK or #Grayscale ), and the rest are component intensities (1 for grayscale, 4 for CMYK).
      Note: The alternate color specifies an equivalent representation for the full colorant intensity . Occurrences of the same spot color with different tints should have the same alternate color specifier.
      If the alternate color is not specified, XEP looks it up in SpotColor matching table (path to the table is defined by the <SPOT_COLOR_TRANSLATION_TABLE> option); if no matches found, black color in grayscale color space is used.

      Examples:
      rgb-icc(255,255,0, #SpotColor,'PANTONE Orange 021 C',0.33)
      rgb-icc(255,255,0, #SpotColor,'PANTONE 169 M',0.5, #CMYK,0,0.2,0.2,0)
      rgb-icc(255,255,0, #SpotColor,MyColor,0.33, #Grayscale,0.5)
  5. Registration color . The following specifier produces registration (all-colorants) color output:
    • rgb-icc() function with built-in #Registration pseudo profile. Tint intensity is specified as a real value in the range 0.01.0 , the 5th argument to the function. Example:
      rgb-icc (128, 128, 128, #Registration, 0.5)

XSL 1.1 Support

XEP includes stylesheets to convert XSL 1.1 elements and attributes to elements and attributes from XSL 1.0 and RenderX extensions. All elements and attributes which exist in both XSL 1.1 and XSL 1.0 are left without changes. The elements and attributes which exist only in XSL 1.1 are converted into corresponding elements and attributes from RenderX extensions. The stylesheets support conversion for the following features:

  1. Document Outline (Bookmarks)
  2. Indexes
  3. Last Page Number Reference
  4. Change Bars
  5. Folio Prefix and Suffix

Since there is no correspondence in RenderX extensions for some elements and attributes from XSL 1.1, they will be ignored during conversion. Following is a list of unsupported elements and attributes:

  • fo:page-sequence-wrapper
  • fo:flow-map
  • fo:flow-assignment
  • fo:flow-source-list
  • fo:flow-target-list
  • fo:flow-name-specifier
  • fo:region-name-specifier
  • @allowed-height-scale
  • @allowed-width-scale
  • fo:index-page-number-prefix
  • fo:index-page-number-suffix
  • @index-class
  • @merge-ranges-across-index-key-references
  • @merge-pages-across-index-key-references

Document Outline (Bookmarks)

§ XSL 1.1 Object/Property Name RenderX Extensions Object/
Property Name
6.11.1 <fo:bookmark-tree> <rx:outline>
6.11.2 <fo:bookmark> <rx:bookmark>
6.11.3 <fo:bookmark-title> <rx:bookmark-label>
7.23.6 external-destination external-destination
7.23.8 internal-destination internal-destination
7.23.10 starting-state collapse-subtree

Indexes

§ XSL 1.1 Object/Property Name RenderX Extensions Object/
Property Name
6.10.2 <fo:index-page-number-prefix> No correspondence, ignored
6.10.3 <fo:index-page-number-suffix> No correspondence, ignored
6.10.4 <fo:index-range-begin> <rx:begin-index-range>
6.10.5 <fo:index-range-end> <rx:end-index-range>
6.10.6 <fo:index-key-reference> <rx:index-item>
6.10.7 <fo:index-page-citation-list> <rx:page-index>
6.10.8 <fo:index-page-citation-list-separator> list-separator
6.10.9 <fo:index-page-citation-range-separator> range-separator
7.24.1 index-class No correspondence, ignored
7.24.2 index-key rx:key
7.24.3 page-number-treatment link-back
7.24.4 merge-ranges-across-index-key-references No correspondence, ignored
7.24.5 merge-sequential-page-numbers merge-subsequent-page-numbers
7.24.6 merge-pages-across-index-key-references No correspondence, ignored
7.24.7 ref-index-key <rx:index-item> / ref-key
7.30.8 id id
7.30.13 ref-id ref-id

Last Page Number Reference

§ XSL 1.1 Object Name RenderX Extensions Object Name
6.6.12 <fo:page-number-citation-last> <rx:page-number-citation-last>

The only required attribute, ref-id , specifies the id of the element whose last page number is retrieved.

Change Bars

§ XSL 1.1 Object Name RenderX Extensions Object Name
6.13.2 <fo:change-bar-begin> <rx:change-bar-begin>
6.13.3 <fo:change-bar-end> <rx:change-bar-begin>

All properties of <fo:change-bar-begin> and <fo:change-bar-end> map to themselves.

Folio Prefix and Suffix

§ XSL 1.1 Object Name XSL 1.0 Object Name
6.6.13 <fo:folio-prefix> <the content>
6.6.14 <fo:folio-suffix> <the content>

The content of <fo:folio-prefix> ( <fo:folio-suffix> ) is added inline before (after) all occurrences of <fo:page-number> , <fo:page-number-citation> , and <fo:page-number-citation-last> referring to elements in the respective <fo:page-sequence> . In case of <fo:page-number> it is always the current page sequence.

Extensions to the XSL 1.0 Recommendation

XEP implements several extensions to the Specification, placed into a separate namespace: xmlns:rx="http://www.renderx.com/XSL/Extensions" . They add support for useful functionality that cannot be expressed by XSL Formatting Objects.

Document Information

This extension permits passing a set of name/value pairs to the generator of the output format. A typical application is setting PDF document info fields ( ‘Author’ and ‘Title’ ). Implementation uses two extension elements: <rx:meta-info> and <rx:meta-field> .

  • '<rx:meta-info>' — This element is merely a container for one or more <rx:meta-field> elements. It should be the first child of <fo:root> .
  • '<rx:meta-field>' — This element specifies a single name/value pair. It has two mandatory attributes: name and value . Current implementation of the PDF and PostScript generators recognize four possible values for name :
    • name = "author"- fills the ‘Author’ field in the resulting PDF file with a string specified by the value property.
    • name = "creator" - fills the ‘Creator’ field.
    • name = "title" - fills the ‘Title’ field.
    • name = "subject" - fills the ‘Subject’ field.
    • name = "keywords" - fills the ‘Keywords’ field.

    The ‘Producer’ field in the PDF file is set to "XEP 4.13" ; there is no means to control it from the source file. All other values for name are treated as custom meta-fields and appear in the same dictionaries in PostScript and PDF as predefined meta-fields. Unicode values for name are not supported.
    In the PostScript generator module, the document info fields are added using the pdfmark operator. The respective fields are filled when PostScript is converted to PDF using Adobe Acrobat Distiller or GhostScript .

Document Outline (Bookmarks)

Implementation of a document outline uses the following three extension elements:

  • <rx:outline> - The top-level element of the document outline tree. It should be located before any <fo:page-sequence> elements, and after the <fo:layout-master-set> and the <fo:declarations> elements (if present). It contains one or more <rx:bookmark> elements.
  • <rx:bookmark> - This element contains information about a single bookmark. It contains a mandatory <rx:bookmark-label> element as its first child, and zero or more nested <rx:bookmark> elements that describe nested bookmarks. Bookmark destination is expressed either by internal-destination property (for internal navigation), or by external-destination (for extra-document links). The initial presentation of the children bookmarks is controlled by collapse-subtree attribute. Values are either "true" (collapse children) or "false" (expand children).
  • <rx:bookmark-label> - This element contains text of a bookmark label. It must be the first child of its parent <fo:bookmark> . Content of this element should be plain text.

Indexes

Building page number lists for back-of-the-book indexes is a common task. It is relatively easy to collect a list of references to index terms in the text; but then, to turn them into a real index entry, you should exclude repeated page numbers and merge adjacent numbers into ranges. Neither of these two operations can be done in XSL 1.0. Therefore, XEP supports an extension for this purpose.

The task of building an index can be split in two subtasks:

  • Mark up occurrences of index terms in the main text.
  • Specify composition and formatting of page number lists in the index.
Index Term Markup
In order to mark up occurences of the index terms in the text, XEP introduces a special extension attribute: rx:key . It can be specified on any element that can take an id attribute; unlike the latter, it need not be unique across the document. Its value is used as a key to select elements for the page number list. For example, an index term to the word "rendering" might look like this:
The process of converting XSL-FO to a printable format
is called <fo:inline rx:key="key.render">rendering.</fo:inline>

There is also a mechanism to specify an explicit range, not distinct elements. Two extension elements serve this purpose:

  • <rx:begin-index-range> — Starts a range. It takes two attributes, both required:
    • id — A unique identifier used to define the limits of the range.
    • rx:key — Index key used to select the range into a page number list.
  • <rx:end-index-range> — Ends a range. It takes one attribute, required:
    • ref-id — A reference to the id attribute of the <rx:begin-index-range> that started the range.


These two elements always form a pair. These elements may be located anywhere inside <fo:flow> ; there are no constraints on their nesting with respect to other elements.

Index Entries

In the index, the actual page reference is created by another extension element, <rx:page-index> . It picks elements from the text by their rx:key properties, and produces a sorted list of their page numbers, eliminating duplicates.

<rx:page-index> should contain one or more <rx:index-item> elements as children. Each <rx:index-item> has a required ref-key attribute, and selects elements that have an rx:key attribute with the same value.

A distinct element bearing the appropriate rx:key value is represented as follows:

  • If it fits completely onto one page, it is represented as a single page number.
  • If it spans multiple pages, its entry is formatted as a range from the first to the last of the spanned pages.

A range (created by a <rx:begin-index-range> and <rx:end-index-range> element pair) is represented as a range from the page where <rx:begin-index-range> is located to the page of its matching <rx:end-index-range> .

A basic entry in an index looks like this:
<fo:inline rx:key="key.elephant">Elephants</fo:inline> live in Africa. …
<fo:inline rx:key="key.elephant">African elephants</fo:inline> have big ears …
…
<fo:block text-align="center" font="bold 16pt Futura">INDEX</fo:block>
<fo:block>
    Elephants <rx:page-index>
                   <rx:index-item ref-key="key.elephant"/>
              </rx:page-index>
</fo:block> 

There are other attributes of <rx:index-item> to control the formatting of the index entry:

range-separator  
Specifies the string used to separate page numbers that form a continuous range. Default is en dash: "–" (U+2013) .
merge-subsequent-page-numbers  
Controls whether sequences of adjacent page numbers should be merged into ranges. Default is "false."
link-back  
If set to "true" , page numbers are made into hyperlinks to the corresponding page. Default is "false."

Besides that, <rx:index-item> can take additional inline attributes, applied to each page number generated from this element. This allows for different presentation styles across the list, e.g. To make references to primary definitions bold.

Flow Sections

Flow sections permit splitting the flow into subflows, with different column counts in each subflow. The following element creates flow sections:

<rx:flow-section>  
This element must be a direct child of <fo:flow> . It can be mixed with other block-level elements. It takes two attributes: column-count, the number of columns for the subflow, and columngap, the space between the columns.

Last Page Number Reference

This extension element retrieves the number of the last page occupied by a particular element. Its syntax and semantics are similar to fo:page-number-citation .

<rx:page-number-citation-last>  
The only required attribute, ref-id , specifies the id of the element whose last page number you want to retrieve. In particular, by referencing the id of the <fo:root> element, it is possible to retrieve the number of the last page in the document.
Note: This element is described in XSL 1.1 Working Draft of 17 December 2003. In subsequent versions of XEP, it is likely to move to the standard XSL-FO namespace.

Change Bars

XEP has support for change regions, as described in XSL 1.1 Working Draft of December 16, 2004.

<rx:change-bar-begin>
<rx:change-bar-end>
These elements have exactly the same meaning and properties as listed in the Working Draft for elements <fo:change-bar-begin> and <fo:change-bar-end> , sections 6.3.12 and 6.3.13, respectively. In future versions of XEP, when XSL 1.1 will become the W3C Recommendation, they will be moved to the standard XSL-FO namespace.
Note: The content model for these elements is different than the description in the Working Draft. The Working Draft, Section 6.2, says the following about change-bar-begin/end elements: “The following formatting objects are "neutral" containers and may be used, provided that the additional constraints listed under each formatting object are satisfied, anywhere where #PCDATA, %block;, or %inline; are allowed”. This essentially forbids change-bar-begin/end elements to appear almost anywhere in the lists or tables, for example, it’s not possible to mark a whole list-item or table-cell as “changed.” XEP implementation does not have such limitations, change bar anchors can be placed almost anywhere in the flow.

Background Image Scaling and Content Type

In XSL 1.0, there is no provision to scale/size a background image. XEP implements this functionality via the following extension properties:

rx:background-content-height
rx:background-content-width
rx:background-scaling
rx:background-content-type

These properties have exactly the same semantics as content-height , content-width , scaling , and content-type , respectively. They apply to the image specified in background-image property (or inside background shorthand).

Initial Destination

This extension allows you to specify the destination to jump to when the document is first opened. It uses a single extension attribute, rx:initial-destination placed on <fo:root>; its syntax is the same as the internal-destination attribute.

Omitted Initial Header in Tables

This extension permits you to omit a table header at the beginning of a table. This feature can be used to create "continuation headers", which are output only on page breaks. It uses a single extension attribute, rx:table-omit-initial-header placed on <fo:table> . The property has a Boolean value: "true" or "false" — same as for table-omit-header-at-break .

Base URI Definition: xml:base

XEP recognizes and processes xml:base attribute, defined in XML Base Recommendation. It permits you to set the base for resolving relative URIs (link targets, image locations, fonts, hyphenation patterns, etc) for the whole document or a single subtree.

Note: The use of xml:base in XSL is not authorized by the XSL Specification; therefore, this option should be considered a proprietary extension to XSL.

Border and Padding on Regions

In the XSL Recommendation, border and padding properties are permitted on region elements ( <fo:region-body>, <fo:region-before>, <fo:region-after>, <fo:region-start>, and <fo:region-end> ). However, they may accept values of 0 (sic!) . In XEP, non-zero values of these properties result in a border around the respective region area, and its content rectangle is padded by the specified amount.

Note: When validation strictness level is 2 , the validator issues a warning about nonzero borders and padding on regions.

Floats Alignment

Floating figures often need to float towards different sides of the page depending on their parity. However in XSL 1.0 Recommendation there is no means to achieve such effect. XEP supports two additional values for float property of the <fo:float> element. Those values are: "inside" and "outside" . Their meaning is the same as in text-align property defined by XSL 1.0 Recommendation: "inside" value aligns floating block to the inner edge of the page (left for odd pages, right for even pages) and "outside" aligns floating block to the outer edge of the page (right for odd pages, left for even pages). This functionality is often used to create margin notes known as "marginalia."

Multicolumn Footnotes

Some documents have many short footnotes per page, and according to the Recommendation all the footnotes are stacked ontop of each other. This results in a lot of white space to the right of the footnotes in footnote-reference-area.

XEP supports two additional attributes: footnote-column-count and footnote-column-gap on <fo:region-body> . They have the same meaning as column-count and column-gap and result in footnote-reference-area having the required number of columns separated with gaps. XEP balances the footnotes among the columns in footnote-reference-area, which makes the area be filled better and have smaller height, leaving more space for the body.

Note: The balancing algorithm is iterative and may affect performance in corner cases. The best quality of balancing is achieved in the most common cases: for short footnotes.

Unique Footnotes

There is a user's request to collapse footnote-bodies on a page if their anchors read the same. This is useful if, for example, several values in table cells must be marked with one and the same note. The Recommendation does not provide a way to achieve this, because one must know beforehand how the footnotes will be distributed among pages.

XEP can handle this request properly. A footnote-body will not be added to the footnote-reference-area if there is a footnote-body starting on this page wich has the same value of id . In other words, footnotes with equal footnote-body/@id collapse to one per page.

Note: If a footnote-body starts on page N and continues on page N+1, there may appear another footnote-body with the same id on page N+1: the tail of a footnote may not collapse.
Note: Collapsed footnote-bodies are treated as if they were empty. Any special content (a term for the index, a target for a link, a part of a 'paired' element such a change-bar or an index-range) will be ignored. Avoid using such content together with the 'unique footnotes' feature.

Watermark

In mass print large number of pages differ in content, but not in static regions. XEP spends a significant share of time formatting static regions on each page. The request is to avoid formatting common parts of pages on each page to save time, and instead pick them up from an XEPOUT file prepared beforehand.

XEP provides an extension for this request: rx:watermark attribute on <fo:simple-page-master> . The value of rx:watermark is an URI reference to an XEP intermediate format file.

For every page created with a given page master, the content of the first <xep:page> of master's watermark file will be drawn before anything else on the page.

Note: This extension saves formatting time for static contents, but does not reduce the time required to generate it to an output format.
Note: Do not forget to remove targets and bookmarks from a watermark file.
Note: No scaling is performed on the content of the watermark file, it is 'played' as is.

Transpromo

Empty space often appears at the bottom of pages, especially of the last pages of page sequences. This space may be used for ads. Arbitrary content of a flow makes it impossible to tell how much space will be left on the last page beforehand, so for arbitrary content there is no way to determine the size of the ads box that will fit without making the flow content go to yet another page.

Having a set of ads boxes of different size, users need a way to place the largest such box (just one) that fits on the last page.

'Transpromo' is an extension to the page master selection algorithm that makes XEP iterate over a set of page masters that suite for 'last' until it finds one where all the tail of the flow content fits.

With the extended algorithm users may specify a set of <fo:conditional-page-master-references>, all with page-position='last' , in desired order. These page masters may, for example, have different extent on <fo:region-after>, from large to small values (in order of reading the <fo:conditional-page-master-references> in <fo:repeatable-page-master-alternatives> ). The <fo:page-sequence> will have the respective set of <fo:static-contents> with the ads boxes. The largest box that fits together with the flow content will succeed, and formatting will end.

The extended algorithm works similarly for the page masters for 'only'.

Notes

  1. <fo:instream-foreign-object> can host SVG graphics.
  2. All content is placed inline.
  3. In this version, only plain text can be put inside leaders with leader-pattern = "use-content".
  4. Top-floats (float = "before") area is drawn on top of the following page.
  5. In the current version, markers cannot be specified as children of <fo:wrapper>.
  6. absolute-position = "fixed" works on <fo:block-container> only.
  7. 7.0 7.1 When the background image is repeated along an axis, its offset on this axis is ignored.
  8. space-after.conditionality = "discard" is not implemented, fallback value is "retain".
  9. Supported on <fo:list-item>. On <fo:table-cell> elements, falls back to relative-align = "before".
  10. Maps to height.
  11. Maps to width.
  12. Maps to height.
  13. Maps to width.
  14. Value "treat-as-zero-width-space" for linefeed-treatment is not implemented. This property does not work on inlines.
  15. <string> values for text-align are not implemented. text-align on <fo:table-and-caption> is not implemented.
  16. This property does not work on inlines.
  17. Blurred shadows are not supported; blur radius is ignored.
  18. To transform a Unicode character to uppercase/lowercase, XEP uses methods provided by the runtime (Java or .NET). In order for this property to work as expected, you should use correct Unicode values for glyphs in your fonts, and set up local information in your environment properly.
  19. Two additional values, "inside" and "outside", are supported. Their meaning is the same as in text-align property.
  20. "indent" value is not implemented.
  21. 21.0 21.1 21.2 .within-page component is unsupported; it is mapped to .within-column. Only "auto" and "always" values are recognized properly: numeric values are treated as "always". In tables, keep-with-previous / keep-with-next traits ignore table headers and footers: e.g. keep-with-previous condition specified on a row will keep it with the previous one regardless of the intervening header. If specified on the first row of the first <fo:table-body> in a table, keep-with-previous will attach the whole table to the preceding block-level element.
  22. Supported on side floats and absolutely positioned and rotated block-containers with fixed dimensions. When "error-if-overflow" is specified, a warning is issued on overflow, and the element is discarded in the same way as for "hidden" value.
  23. In PDF and PostScript generators, URLs starting with explicit "file:" protocol specification are rendered as PDF-to-PDF links ("remote go-to actions"). All other links are treated as Internet URIs, and open in a browser.
  24. show-destination is honored for creation of links between PDF documents ("remote go-to actions") in PDF and PostScript generators. In other cases, the attribute is not applicable.
  25. Only "before" and "after" values are implemented: caption-side = "start" falls back to "before," and caption-side="end" falls back to "after."
  26. In the current implementation, all cells present in the source document are shown regardless of whether their content is empty; cells not presented in the source aren't visible at all.
  27. Bidi implementation differs from Unicode Bidi algorithm: any markup element opens a new level of embedding. Consequently, unicode-bidi = "normal" is not supported (treated as "embed"); see detailed discussion below.
  28. Only "lr-tb" and "rl-tb" values are supported. All other values are treated as "lr-tb."
  29. In addition to protocols provided by the runtime (Java or .NET), XEP supports data: URI scheme ( RFC 2397 ).
  30. z-index property is supported for block-containers with absolute-position="fixed".


Back to XEP User Guide

Personal tools