Support Home
XEP User Guide
© Copyright 2005-2010 RenderX, Inc. All rights reserved.
This documentation contains proprietary information belonging to RenderX, and is provided under a license agreement containing restrictions on use and disclosure. It is also protected by international copyright law.
Because of continued product development, the information contained in this document may change without notice. The information and intellectual property contained herein are confidential and remain the exclusive intellectual property of RenderX. If you find any problems in the documentation, please report them to us in writing. RenderX does not warrant that this document is error-free.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means - electronic, mechanical, photocopying, recording or otherwise - without the prior written permission of RenderX.
RenderX
Telephone: 1 (650) 328-8000
Fax: 1 (650) 328-8008
Website: http://renderx.com
Email: support@renderx.com
- 1. Preface
- 2. Overview
- 3. XEP Assistant
- 4. Using the Command Line
- 5. Configuring XEP
-
- 5.1. Configuring XEP using XEP Assistant
- 5.2. Configuring XEP via the XEP Configuration File
-
- 5.2.1. Configuration Structure
- 5.2.2. Core Options
- 5.2.3. Configuring Output Formats
-
- 5.2.3.1. Unicode Strings in Annotations (PDF, PostScript)
- 5.2.3.2. Initial Zoom Factor (PDF, PostScript)
- 5.2.3.3. PDF Initial View (PDF, PostScript)
- 5.2.3.4. Logical Page Numbering (PDF)
- 5.2.3.5. Page Layout (PDF)
- 5.2.3.6. PDF Viewer Preferences (PDF)
- 5.2.3.7. Treatment of Unused Destinations (PDF, PostScript)
- 5.2.3.8. ICC Profile (PDF)
- 5.2.3.9. PDF/X Support (PDF)
- 5.2.3.10. PDF/A Support (PDF)
- 5.2.3.11. Prepress Support (PDF, PostScript)
- 5.2.3.12. PDF Version (PDF)
- 5.2.3.13. Compression of PDF Streams (PDF)
- 5.2.3.14. Linearization (PDF)
- 5.2.3.15. Document Security (PDF)
- 5.2.3.16. PostScript Language Level (PostScript)
- 5.2.3.17. EPS Graphics Treatment (PostScript)
- 5.2.3.18. Page Device Control (PostScript)
- 5.2.3.19. Page Labeling (PostScript)
- 5.2.3.20. Inserting Custom Comments (PostScript)
- 5.2.3.21. Image Inline Threshold (PostScript)
- 5.2.3.22. Images Treatment in XML Output (XML, SVG)
- 5.2.3.23. SVG viewer resolution (SVG)
- 5.2.4. Configuring Fonts
- 5.2.5. Configuring Languages
- 5.3. Resolution of External Entities and URIs
- 6. XEP AFP Generator
-
- 6.1. Generating AFP Documents
- 6.2. Fonts
- 6.3. Images
- 6.4. Highlight Color Support
- 6.5. Graphics Support
- 6.6. Barcodes Support
- 6.7. FORMDEF Resource
- 6.8. Configuring the XEP AFP Generator
- 6.9. Bullets support
- 6.10. International Character Set Support
- 6.11. Limitations of the XEP AFP Generator
- 6.12. Frequently Asked Questions
- 7. XEP SVG Generator
- 8. Appendix A. XSL-FO Conformance
-
- 8.1. XSL-FO Support
-
- 8.1.1. Formatting Objects Supported by XEP
- 8.1.2. Formatting Properties Supported by XEP
- 8.1.3. Notes on Formatting Objects Implementation
- 8.1.4. Supported Expressions
- 8.1.5. Color Specifiers
- 8.1.6. XSL 1.1 Support
- 8.1.7. Extensions to the XSL 1.0 Recommendation
-
- 8.1.7.1. Document Information
- 8.1.7.2. Document Outline (Bookmarks)
- 8.1.7.3. Indexes
- 8.1.7.4. Flow Sections
- 8.1.7.5. Last Page Number Reference
- 8.1.7.6. Change Bars
- 8.1.7.7. Background Image Scaling and Content Type
- 8.1.7.8. Initial Destination
- 8.1.7.9. Omitted Initial Header in Tables
- 8.1.7.10. Base URI Definition: xml:base
- 8.1.7.11. Border and Padding on Regions
- 8.1.7.12. Floats Alignment
- 8.1.7.13. Multicolumn Footnotes
- 8.1.7.14. Unique Footnotes
- 8.1.7.15. Watermark
- 8.1.7.16. Transpromo
- 9. Appendix B. Linguistic Algorithms
- 10. Appendix C. Supported Fonts
- 11. Appendix D. Supported Graphic Formats
- 12. Appendix E. XEP Intermediate Output Format Specification
- 13. Appendix F. Accessibility Support in XEP
- 14. Appendix G. List of Output Generators' Options
- 15. Appendix H. Configuration File DTD
This section contains the following topics:
The RenderX User Guide provides background information about what XEP does and explains how to use the product. The manual is divided into the following sections:
-
Overview
-
XEP Assistant
-
Using the Command Line
-
Configuring XEP
-
XEP AFP Generator
-
XEP SVG Generator
XEP runs on most systems where Java Virtual Machine 1.1.8 or newer is available. This includes:
-
Unixes;
-
Microsoft Windows;
-
Linux;
-
Mac OS X;
-
Other platforms and Operation Systems.
The Java edition of XEP requires a Java VM 1.2 or higher to run properly. Sun JRE version 1.3 or later is highly recommended. AFP Backend works with all versions of JRE 1.4 up to 1.6.0_01.
AFP Backend requires charsets.jar installed with JRE. By default, JRE is installed without charsets.jar file. Please run JRE installer and check the "additional languages support" checkbox.
Note:
Actual checkbox name may vary for different versions of JRE.
XEP 4.14 demonstrates best performance running under JRE 1.6. This version of JRE is shipped within XEPWin distributions.
In order to view PDF output, a viewer is required. Adobe provides a free one which can be downloaded and installed from the Adobe website.
To view PostScript files, one option is to use GhostView, which may be used for viewing PDF as well. Versions are available for most operating systems.
The following table lists acronyms used in this manual:
Table 1. Acronyms
| Acronym | Full Term |
|---|---|
| CJK | Chinese Japanese Korean (Unicode UTF-8 encoding standard for Asian character set) |
| CMYK | Cyan-Magenta-Yellow-Key/blacK (4-color ink model used for printing) |
| DTD | Document Type Definition |
| IPA | Internet Protocol Address |
| SVG | Scalable Vector Graphics |
| URL | Uniform Resource Locater (world wide web address) |
| W3C | World Wide Web Consortium |
| XML | eXtensible Markup Language |
| XSL | eXtensible Stylesheet Language |
| XSL-FO | eXtensible Stylesheet Language Formatting Objects |
| JRE | Java Runtime Environment |
| JDK | Java Development Kit |
You can contact RenderX technical support by:
-
Using the RenderX support portal at http://renderx.com/support/index.html
-
Sending an email to support@renderx.com
-
Calling 1 (650) 328-8000
This section contains the following topics:
XEP is a library of Java classes that converts XML data to printable formats, such as PDF, PostScript, AFP and SVG. XEP accepts either an XSL-FO file, or an XML file paired with an XSL stylesheet, as input. In the latter case, XEP uses an internal XSLT transformer to preprocess the XML file according to the XSL stylesheet, thereby converting it to an XSL-FO file. The XEP engine then processes the XSL-FO file.
The logical flow of document processing can be divided into three phases, as illustrated in the following figure:
-
Parsing - XEP reads the XSL-FO file and creates an internal representation of the file in memory.
-
Formatting - The XSL-FO is fed into the formatter which creates and fills pages according to the specification defined in the XSL-FO document. Results of the formatting stage can be output as XML to be further processed later.
-
Generating - The XSL-FO file is converted to the requested output format - PDF, PostScript, AFP or SVG.
XEP can be run in three different environments:
-
XEP Assistant - XEP includes a GUI-based tool for more comfortable transformation of files, suitable for users that prefer graphic interface. For a detailed description, refer to XEP Assistant.
-
Command Line - XEP can be run from the command line as described in Using the Command Line.
XEP can be configured to allow users to apply settings, such as fonts, languages and formatting options, according to their preferences. For a detailed reference please refer to Configuring XEP.
This section provides an introduction to the basic terms that are used throughout this documentation.
- PDF (Portable Document Format)
-
PDF is a universal file format that preserves the fonts, images, graphics, and layout of any source document, regardless of the application and platform that were used to create it. See the Adobe Web site http://www.adobe.com for more information.
- PostScript®
-
Adobe® PostScript® is the worldwide printing and imaging standard. Used by print service providers, publishers, corporations and government agencies around the globe, Adobe PostScript 3 gives you the power to print visually-rich documents. See the Adobe Web site http://www.adobe.com for more information.
- AFP (Advanced Function Printing)
-
AFP is an architecture standard for High Volume Transaction Output, supported by such vendors of printing equipment as IBM, Kodak and Xerox. AFP has built-in support for text and raster graphic output, vector graphic, vector and raster fonts, as well as many other features. The entire document structure of AFP document is organized by means of a higher level protocol called MO:DCA which links all printable objects together and builds the whole document.
- SVG
-
SVG is a language for describing two-dimensional graphics in XML. A World Wide Web Consortium specification. See the W3C website http://www.w3.org/TR/SVG/ for more information.
- XSL-FO
-
XSL, Formatting objects. A standard way of specifying how content should be presented. A World Wide Web Consortium specification. See the W3C website http://www.w3.org/TR/xsl/ for more information.
This section contains the following topics:
XEP contains a user-friendly GUI tool, called XEP Assistant. Use of XEP Assistant simplifies rendering from XML or XSL-FO into the desired output format.
To open XEP Assistant, browse to the XEP Installation
directory and launch x4u.bat or x4u bash script.
To render a file, first of all, you must open the XML or XSL-FO file you wish to publish.
Once an XML file is open, it must first be "transformed" before it can be formatted to PDF, PostScript, AFP or SVG output. "Transforming" refers to the assignment of various settings required to apply an XSL stylesheet to your XML file. The result of the transforming is that the XML file is transformed into an XSL-FO. The XSL-FO is than formatted to your final output format (PDF, PS, AFP or SVG).
-
From the main menu, click Formatting.
The Formatting menu is displayed.
-
From the Formatting menu, click Start.
The Formatting settings dialog box appears.
-
Set the desired settings as described in the following table.
Table 2. Formatting Settings
Parameter Description Stylesheet Apply stylesheet Check the Apply stylesheet checkbox to apply a stylesheet (XSL) to the XML file. Click Browse to browse to the location of the XSL file you wish to apply as a stylesheet to your XML file. Transformation parameters This button is only enabled when the Apply Stylesheet checkbox is selected. Refer to Figure 5, and Table 3 for a complete description. Output Format Select the format to which you want to render the XML file. Available options are PDF, PS, AFP and SVG. Output File Select the location and name of the file to which the output will be saved. The default output file name is the identical path and file name as the current XML file with the file extension of the chosen output type.
Note:
If a file with the same name already exists in the chosen location, the new file will overwrite the preexisting file with no warning.
Set Resource The Use Custom Resource section is only enabled when AFP is selected as the output format. Click Browse to select the location of the resource file. A resource can be attached to an AFP document to control certain reusable objects like images or FORMDEFs. Viewer Display With Check the Display With checkbox to automatically display the output once rendering is complete. Browse to the location of the program with which you wish to view the rendered file. -
Click OK to format the file, and Cancel to cancel the formatting.
-
From the Formatting settings dialog box, click the Transformation parameters button (only enabled when the Apply stylesheet checkbox is selected).
The XSL Parameters dialog box appears.
-
Fill in the fields as described in the following table:
Table 3. XSL Parameters
Field Description parameter The name of the variable used in the XSL file to represent a parameter value. value The value corresponding to the variable. -
Click Add to add a new parameter, or highlight a parameter and click Delete to delete the selected parameter.
-
Click OK to apply changes, or click Cancel to close the dialog box without applying your changes.
This section contains the following topics:
This topic describes how to run XEP from the command line.
XEP can be run from the command line, as follows:
-
On all platforms, by invoking Java directly from the command line.
-
On Windows, XEP can be run from a Command Prompt window via the
xep.batbatch file. -
On Linux, MAC, and UNIX, XEP can be run from a command shell, via the
xepbash script.
To learn more about the xep.bat batch file or
the xep bash script, open the file in a text editor.
These files use standard scripting features available in the operating
system.
The syntax of the Java command is:
java com.renderx.xep.XSLDriver {options} {switches} {arguments}The above syntax has been simplified by assuming that the directory
containing the Java executable is specified in your PATH environment
variable, and that the full path of the xep.jar file
is in your CLASSPATH environment variable. If you specify
an XSL file to convert an XML source document into XSL-FO, then it is
assumed that saxon.jar or xt.jar
are also specified in your CLASSPATH environment variable.
The syntax of the Windows batch and Linux/MAC shell command is:
xep {options} {switches} {arguments}The above syntax assumes that the full path to the Windows batch file
xep.bat or the Linux/MAC shell script
xep is specified in the PATH
environment variable, or that the current directory is the directory
containing the Windows batch file or Linux/MAC shell script.
The options, switches, and arguments are the same whether XEP is run via Java, via a Windows batch file, or via a Linux/MAC shell script.
The XEP options are used to configure and customize the behavior of the XEP rendering engine.
XEP requires a configuration file in order to run. By default, the
formatter looks for a file named xep.xml in the
current directory. If a different configuration file is used, the path to
the configuration file must be specified on the command line.
XEP is a flexible tool in which the configuration can be customized according to your preferences. There are several methods to customize XEP. These methods are summarized in the following table:
Table 4. Customizing XEP Configuration
| Customization | Description | Syntax |
|---|---|---|
|
Editing the configuration file. |
The xep.xml configuration file can be
customized, thereby customizing all transformations. There are two
ways to customize the file:
|
For editing xep.xml in a text editor,
see the section called “Configuring XEP via the XEP Configuration File”.
For the XEP Assistant, see the section called “Configuring XEP using XEP Assistant”. |
| Setting a custom configuration file. | You can set a custom configuration file in the command line
for a single file transformation. The location of the custom
configuration file can be specified as either a file name in the
local file system or as a URL.
All subsequent file
transformations will continue to use the standard
|
-DCONFIG=<CUSTOM_FILE_PATH> |
| Customizing the XEP configuration through the command line. | In the command line, the configuration can be customized
for a single file transformation. The
Note:It is possible to specify multiple options in the same command line. Note:If there is a contradiction between the configuration file and the customization through the command line, the command line overrides the settings specified in the configuration file. |
-D<OPTION_NAME>=<OPTION_VALUE> |
Note:
If any string contains spaces, the entire string must be enclosed in quotation marks.
The XEP switches configure the behavior of the command line utility.
Table 5. XEP Switches
The XEP arguments instruct XEP how to process a file. For example, arguments may specify the input file, the target format to render to, and the output filename. When multiple arguments are specified, they must be specified in the following order:
( [-xml] <infile> [-xsl <stylesheet>] {-param <name=value>}
| -fo <infile>
| -xep <infile> )
[-format]
[[-<output format>] <outfile>]The XEP arguments are described in the following table.
Table 6. XEP Arguments
This section presents a number of examples of how to run XEP from the command line.
To list all available options and switches:
-
At the system prompt, enter:
xep -help.A list of all available commands is displayed.
c:\myfiles>xep -help XEP 4.14 build 20081212 java com.renderx.xep.XSLDriver {<option>} {-quiet | -version | -valid | -hosted | -help} ( [-xml] <infile> [-xsl <stylesheet>] {-param <name=value>} | -fo <infile> | -xep <infile> ) [-f] [[-<output format>] <outfile>] Available output formats: at (XEP), pdf (PDF), afp (AFP), svg (SVG), ps (Postscript), xep (XEP).
To view the version of XEP you are currently running:
-
At the system prompt, enter:
xep -version.The version you are currently running as well as the build are displayed.
c:\myfiles>xep -version XEP 4.14 build 20081212 (document [system-id file:stdin] -
Press
<Ctrl> + <C>to exit XEP interactive mode.
To render an XML document to PDF:
-
To render the XML document
CommandLine.xmlto PDF, using the stylesheetcustom-fo.xslto transform the XML to an XSL-FO document and relying on the default settings for the output format and output filename, at the system prompt, enter:xep CommandLIne.xml -xsl custom-fo.xsl
This section contains the following topics:
This section describes how to configure XEP according to your preferences by using XEP Assistant.
To configure XEP:
-
From the main menu, select Options.
The Options menu is displayed.
-
From the Options menu, select Edit.
The XEP Configuration dialogue box is displayed.
-
Click the Main tab, the Backends tab, the Languages tab or the Fonts tab.
For See Main tab the section called “Configuring Main Settings” Backends tab the section called “Configuring Backends” Languages tab the section called “Configuring Languages” Fonts tab the section called “Configuring Fonts” -
Configure the required parameters and click Save to save and close, or Exit to close without saving your changes.
The default configuration settings can be set in the Main tab.
Table 7. XEP Configuration Main Tab Parameters
Using Backends, you can control certain properties in the output documents. There are different available properties for each output type. Select the output type and then configure the properties for the specific output type selected. Refer to the appropriate figure and table for more information on each output type.
To select the output type:
-
On the Backends tab, click Select backend.
-
Select PDF, PostScript, AFP or SVG.
The Backend Parameters screen populates with parameters based on the selected backend.
Table 8. XEP Configuration Backends Tab PDF Parameters
Table 9. XEP Configuration Backend Tab for Configuring PostScript Parameters
Table 10. XEP Configuration Backends Tab AFP Parameters
Please refer to the section called “Configuring the XEP AFP Generator” of this document for details.
To view and edit an AFP font and its sub values:
-
Click the AFPFonts drop down box (see Figure 9).
-
Select the font you wish to view/edit.
Note:
AFP font names are comprised of the word
<AFPFont>followed by a comma and the XEP font name, such as<AFPFont, Verdana>.All sub values are populated based on the font selected.
-
View or edit all AFP font sub values.
-
Click AddAFPFont (see Figure 9).
A dialog box opens containing a list of all supported fonts as displayed in the following figure:
-
Select the font you wish to add to the AFP fonts.
-
Click OK to add the font or Cancel to close the box without adding a new font.
The selected font is added.
-
From the AFPFonts drop down box, select the font you wish to remove (see Figure 9).
-
Click RemoveAFPFont.
The selected font is removed.
Table 11. XEP Configuration Backends Tab SVG Parameters
Languages can be configured in the Languages tab.
Table 12. XEP Configuration Languages Tab
Fonts are categorized into families, which is the basic configuration unit in XEP, and then further into groups. A font family is a set of fonts that share a common design but differ in stylistic attributes, such as upright or italic, light or bold. A group consists of several font families wrapped into one container element. Groups can be nested, forming complex font hierarchies.
In the left column, there is the font hierarchy that contains groups, families, and fonts. Click on a node to display and edit its common attributes. Double-click a node to open its children.
Table 13. XEP Configuration - Fonts Tab Parameters
This topic describes in detail how to configure XEP by creating or modifying an XEP configuration file.
XEP is controlled by a single configuration file which contains core formatting options, fonts available to the formatter, and language-specific data.
The XEP configuration file must always be accessible to the
formatter. Methods for locating the configuration file are
platform-dependent. Please refer to specific platform documentation for
details. By default, the formatter looks for a file named
xep.xml in the directory where it is currently
running.
The configuration file is an XML document in a special namespace:
"http://www.renderx.com/XEP/config". The root of the
configuration file is a <config>
element which includes three major subsections:
-
<options>- Options for XEP rendering core and backends are defined inside the<options>element. -
<fonts>- Fonts configuration is contained inside the<fonts>element. -
<languages>- Hyphenation and language-dependent parameters are configured in the<languages>element.
Some parameters can accept URLs as values. In such cases, the
location of the configuration file is used as a base to resolve relative
URLs. The base URL can be overridden for any subtree of the
configuration file, by utilizing the xml:base attribute.
Note:
All relative URLs in parameter values stored in a referenced
file are resolved with respect to that file, rather than the top-level
configuration file. Attribute xml:base in the referrer file has
no effect on URLs that are contained in another file.
The use of a monolithic configuration file is usually the most
convenient way to store the configuration, as it simplifies switching
between different XEP configurations, and facilitates environmental
tuneup. However, occasionally it may be wiser to move parts of the
configuration into separate files, such as when font configuration is
reused across multiple setups. The configuration file supports
modularization. Any container element can be moved into a separate XML
file whose location is specified by an href attribute.
XEP is controlled by several
options which can be set in the configuration file.
An option is defined by an <option>
element. It has a name and an associated value:
name=value<options> element. The following core options
are defined for XEP 4.14:
Table 14. Core Options
| Option | Possible Values | Description |
|---|---|---|
LICENSE |
free text Default: |
The location of the license file. At startup, XEP looks for a license file, and only runs if the signature on the license matches the public key associated with the specific edition of the formatter. Additionally, this file is used as an access key to XEP online update service. The parameter
can be specified either as a file name in the local file system,
or as a URL. In addition to common protocols,
|
VALIDATE |
true, false Default: true |
Controls the input validation.
CautionIn non-validating mode, XEP uses less memory, and runs faster. However, less errors are intercepted, and the results of formatting are less predictable for malformed print. This setting is discouraged unless your stylesheets are throughly debugged. |
DISCARD_IF_NOT_VALID |
true, false Default: true |
Controls the termination of processing upon unsuccessful validation. |
STRICTNESS |
|
Determines the validator's level of strictness. |
SUPPORT_XSL11 |
true, false Default: true |
Turns on/off XSL-FO 1.1 support.
Note:If false is selected, XEP runs faster and uses less memory. |
TMPDIR |
Default: none |
The path to the directory for temporary files. If
set, this parameter must point to a writable directory,
specified either as a path in the local file system or as a
file URL. To disable writing temporary files to disk, specify
Note:To avoid file name clashes, a separate temporary directory should be specified for each process running XEP. |
BROKENIMAGE |
free text Default:
|
The icon inserted as a replacement for broken or missing images. The parameter
can be specified either as a file name in the local file system,
or as a URL. In addition to the common protocols,
|
PAGE_WIDTH |
Default: 576pt (8 in) | Sets the default page width. |
PAGE_HEIGHT |
Default: 792pt (11 in) | Sets the default page height. |
KERN |
true, false Default: true |
Controls whether the formatter uses or ignores glyph kerning data to determine character positions. |
ENABLE_ACCESSIBILITY |
true, false Default: false |
Controls whether the formatter uses a special mode to create accessible PDF documents. |
OMIT_FOOTER_AT_BREAK |
true, false Default: false |
Defines whether tables footers are omitted at breaks by default. |
SPOT_COLOR_TRANSLATION_TABLE |
free text |
Path to Spotcolor-to-CMYK translation table file for use
in rgb-icc() function with
#SpotColor pseudo profile.
The parameter
can be specified either as a file name in the local file system,
or as an URL. In addition to the common protocols,
Default: none, all spot colors come out black. Note:This table was hard-coded in previous versions of XEP. Due to license restrictions, it has been removed from the current version. Users are recommended to download this table from PANTONE® site and specify this option accordingly. |
- Unicode Strings in Annotations (PDF, PostScript)
Initial Zoom Factor (PDF, PostScript)
PDF Initial View (PDF, PostScript)
Logical Page Numbering (PDF)
Page Layout (PDF)
PDF Viewer Preferences (PDF)
Treatment of Unused Destinations (PDF, PostScript)
ICC Profile (PDF)
PDF/X Support (PDF)
PDF/A Support (PDF)
Prepress Support (PDF, PostScript)
PDF Version (PDF)
Compression of PDF Streams (PDF)
Linearization (PDF)
Document Security (PDF)
PostScript Language Level (PostScript)
EPS Graphics Treatment (PostScript)
Page Device Control (PostScript)
Page Labeling (PostScript)
Inserting Custom Comments (PostScript)
Image Inline Threshold (PostScript)
Images Treatment in XML Output (XML, SVG)
SVG viewer resolution (SVG)
XEP can render to several different output formats including PDF, PostScript, AFP and SVG. Certain properties of output documents can be controlled in two ways:
-
Processing Instructions - The processing instructions are used to specify information that does not affect formatting and is safely ignored by the XSL-FO processors.
Each processing instruction begins with a prefix that identifies the output generator to which the instruction is addressed. For the standard PDF generator, the prefix is
<?xep-pdf-, for PostScript, the prefix is*><?xep-postscript-, for AFP, the prefix is*><?xep-afp-and for SVG, the prefix is*><?xep-svg-. Generators ignore processing instructions that do not start with their assigned prefixes. In particular, PDF generator instructions are invisible to the PostScript generator, and vice versa.*>Instructions that pertain to an entire document should be placed at the top of the document, before or right after the
<fo:root>start tag. Instructions that pertain to a single page of the documentation should be specified inside<fo:simple-page-master>object used to generate that page. -
Generator Options - Generator options affect the entire output document. Some features affect only parts of the input document and can only be expressed with processing instructions.
Generator Options can be used to set default settings for output generators. They are specified inside the
<options>element in the configuration file. To distinguish them from the core options, they are wrapped in the<generator-options>element. The following table describes the attribute of the<generator-options>tag:Table 15. Generator-Options Attributes
Attribute Possible Values Description FORMATPDF, PS, AFP, SVG Format defines the target output format for the generator. The following is an example of a fragment which turns on the linearization for the PDF generator and sets initial zoom factor to
fit-widthfor both PostScript and PDF backends:<generator-options format="PDF"> <option name="LINEARIZE" value="true"/> <option name="INITIAL_ZOOM" value="fit-width"/> </generator-options> <generator-options format="PostScript"> <option name="INITIAL_ZOOM" value="fit-width"/> </generator-options>
All options can be controlled using processing instructions, and some options can be controlled by use of generator options. The following sections describe available processing instructions and generator options as well where they can be utilized.
<?xep-pdf-unicode-annotationsvalue?> <?xep-postscript-unicode-annotationsvalue?>
These processing instructions enable or disable the use of
Unicode to represent PDF annotations strings, such as bookmark text
and document info. In PostScript, the information is coded in
pdfmark operators and used for further conversion
to PDF.
The following are possible values:
-
true - Enable use of 16-bit Unicode to represent annotation strings. In this mode, XEP uses 8-bit
PDF Encodingfor strings that can be represented inAdobeStandardcharacter set and 16-bit Unicode for strings containing characters not included inAdobeStandard. -
false - Unicode is not used. Annotations are always represented in 8-bit
PDF Encoding; characters not included in theAdobeStandardset are replaced by bullet symbols. This option may be used to enforce compatibility with older versions of PDF software that do not support Unicode, such as Adobe Acrobat 3.0.
Default: true
This feature can also be controlled by UNICODE_ANNOTATIONS option in the configuration file for PDF and PostScript generators.
<?xep-pdf-initial-zoomvalue?> <?xep-postscript-initial-zoomvalue?>
These processing instructions specify the magnification factor
to be activated when the file is first opened in the PDF viewer. In
PostScript, the information is coded in pdfmark
operators and used for further conversion to PDF.
The following are possible values:
-
auto - Page scaling is not specified.
-
fit - The page is scaled to fit completely into the
view port. -
fit-width - The page is scaled so that its width matches the width of the
view port. -
fit-height - The page is scaled so that its height matches the height of the
view port. -
number or percentage - The page is scaled by the number or percentage specified in the enabled box.
Default: auto
This feature can also be controlled by the INITIAL_ZOOM option in the configuration file for PDF and PostScript generators.
<?xep-pdf-view-modevalue?> <?xep-postscript-view-modevalue?>
These processing instructions set the view mode to be activated
in the PDF viewer when the PDF file is rendered and viewed. In
PostScript, the information is coded in pdfmark
operators and used for further conversion to PDF.
The following are possible values:
-
auto - If there are bookmarks in the document, the bookmarks pane is displayed. Otherwise, all auxiliary panes are hidden.
-
show-none - All auxiliary panes are hidden.
-
show-bookmarks - The bookmarks pane is displayed.
-
show-thumbnails - The thumbnails pane is displayed.
-
full-screen - The document is displayed in full screen-mode.
Default: auto
This feature can also be controlled by the VIEW_MODE option in the configuration file for PDF and PostScript generators.
<?xep-pdf-logical-page-numbering value?>
This processing instruction controls a page numbering scheme for the PDF document.
The following are possible values:
-
true - Logical page numbers are written to the PDF file.
-
false - Logical page numbers are ignored.
Default: true
Note:
Adobe Acrobat has a special check box Use logical page numbers. To show logical page numbers of a PDF document, make sure this control is enabled.
This feature can also be controlled by the LOGICAL_PAGE_NUMBERING option in the configuration file for PDF generator.
<?xep-pdf-page-layout value?>
This processing instruction controls initial page layout when a PDF document is open.
The following are possible values:
-
auto - Uses settings of viewer application.
-
single-page - Displays one page at a time.
-
continuous - Displays pages continuously in one column.
Default: auto
This feature can also be controlled by the PAGE_LAYOUT option in the configuration file for PDF generator.
<?xep-pdf-viewer-preferences value?>
This processing instruction controls viewer preferences for a PDF document.
The value is a comma or space separated list of keywords. Each one enables the respective viewer option. The following are supported keywords:
-
hide-toolbar - Hides the viewer application's tool bars when the document is active.
-
hide-menubar - Hides the viewer application's menu bar when the document is active.
-
hide-window-ui - Hides user interface elements in the document's window (such as scroll bars and navigation controls), leaving only the document's contents displayed.
-
fit-window - Resizes the document's window to fit the size of the first displayed page.
-
center-window - Positions the document's window in the center of the screen.
-
display-document-title - Controls whether the window's title bar displays the document title taken from the "title" entry of
<rx:meta-info>. If absent, the title bar instead displays the name of the PDF file containing the document.
Default: empty list
This feature can also be controlled by the VIEWER_PREFERENCES option in the configuration file for PDF generator.
<?xep-pdf-drop-unused-destinationsvalue?> <?xep-postscript-drop-unused-destinationsvalue?>
These processing instructions specify whether named destinations
are created for objects not referenced within the document. In
PostScript, the information is coded in pdfmark
operators and used for further conversion to PDF.
The following are possible values:
-
true - Named destinations are created only for objects used as targets in
internal-destinationattributes. -
false - Named destinations are created for all objects that have an
idattribute.
Default: true
This feature can also be controlled by the DROP_UNUSED_DESTINATIONS option in the configuration file for PDF and PostScript generators.
<?xep-pdf-icc-profile URL?>These processing instructions specify a characterized printing
condition. PDF/X and PDF/A-1 specifications require the presence of the
characterized printing condition ( /OutputIntent
entry in the PDF catalog dictionary). URL
is the URI of the ICC file. It should follow the XSL-FO notation for
uri-specification: url( ).
<?xep-pdf-pdf-x value?>This processing instruction sets PDF/X compliance level.
The following are possible values:
-
none - No PDF/X restrictions are applied.
-
pdf-x-1a - Sets PDF/X-1a compliance level. The rendered PDF will comply with the PDF-X-1a:2001 spec.
-
pdf-x-3 - Sets PDF/X-3 compliance level. The rendered PDF will comply with the PDF-X-3:2001 spec.
Default: none
<?xep-pdf-pdf-a value?>This processing instruction sets PDF/A compliance level.
The following are possible values:
-
none - No PDF/A restrictions are applied.
-
pdf-a-1a - Sets PDF/A-1a compliance level. The rendered PDF will comply with level A of the PDF/A-1:2005 spec.
Note:
PDF/A-1a compliant documents must be tagged. Set ENABLE_ACCESSIBILITY core option to true. -
pdf-a-1b - Sets PDF/A-1b compliance level. The rendered PDF will comply with level B of the PDF/A-1:2005 spec.
Default: none
The following processing instructions define features that support the prepress production workflow.
<?xep-pdf-crop-offsetvalue?> <?xep-postscript-crop-offsetvalue?>
These processing instructions specify offsets from the
meaningful content on the page to the edges of the physical media
(/MediaBox entry in the PDF page dictionary). Its
value is a series of 1 to 4 length
specifiers that set offsets from the edges of the page area (as
specified in the XSL-FO input document) to the corresponding edges of
the /MediaBox. Rules for expanding the value are
the same as for the padding property in
XSL-FO.
<?xep-pdf-bleedvalue?> <?xep-postscript-bleedvalue?>
These processing instructions specify the bleeds — an extra
space around the page area into which the contents of the page may
protrude (/BleedBox entry in the PDF page
dictionary). Its value is a series of 1 to
4 length specifiers that set offsets from the edges of the page area
(as specified in the XSL-FO input document) to the corresponding edges
of the /BleedBox. Rules for expanding the value are
the same as for the padding property in
XSL-FO.
If bleed values exceed the respective crop offsets, the latter are increased to make room for the bleeds.
<?xep-pdf-crop-mark-widthvalue?> <?xep-postscript-crop-mark-widthvalue?>
These processing instructions display crop marks on the page.
value defines line width for the marks;
setting it to 0 disables drawing of crop marks.
<?xep-pdf-bleed-mark-widthvalue?> <?xep-postscript-bleed-mark-widthvalue?>
These processing instructions display bleed marks on the page.
value defines line width for the marks;
setting it to 0 disables drawing of bleed marks.
<?xep-pdf-printer-markURL?> <?xep-postscript-printer-markURL?>
These processing instructions specify additional SVG images to
be drawn in the offset area surrounding the page (specified by
crop-offset and bleed
parameters). Printer marks are clipped to the outside of the bleed
rectangle. This facility can be used to create registration targets
and color bars; the respective sample SVG images are enclosed in XEP
distribution. URL is the URL to the
location of the SVG file. It should follow the XSL-FO notation for
uri-specification: url( ).
<?xep-pdf-pdf-version value?>This processing instruction sets target PDF version.
The following are possible values:
-
1.3
-
1.4
-
1.5
-
any higher version is allowed here, since PDF versions are backward compatible.
Default: 1.4
Note:
When set to 1.3, advanced features of PDF 1.4 are disabled.
This feature can also be controlled by PDF_VERSION option in the configuration file for the PDF generator.
<?xep-pdf-compress value?>This processing instruction controls compression of content streams in PDF.
The following are possible values:
-
true - PDF streams are compressed using the Flate algorithm.
-
false - PDF streams are not compressed. This option is useful for debugging.
Default: true
This feature can also be controlled by the COMPRESS option in the configuration file for the PDF generator.
<?xep-pdf-linearize value?>This processing instruction controls linearization (also known as Web optimization) of the PDF output.
The following are possible values:
-
true - PDF is linearized. This options is used to prepare documents for HTML output.
-
false - PDF is not linearized.
Default: false
This feature can also be controlled by the LINEARIZE option in the configuration file for the PDF generator.
The following processing instructions control PDF security settings.
<?xep-pdf-ownerpassword value?>This processing instruction sets an owner password for the PDF document to value. Owner password gives its holder full control over the PDF document. This unlimited access includes the ability to change the document's passwords and access privilegies.
Note:
Adobe Acrobat by default applies user's access restrictions to owners too. To remove some of these restrictions, go to 'Document Properties -> Security' and choose 'Change Settings' option.
<?xep-pdf-userpassword value?>This processing instruction sets a user password for the PDF document to value. Holders of user password are subject to access restrictions; only operations included in the privilege list are authorized.
<?xep-pdf-userprivileges value?>Sets the default privilege list for users accessing the rendered document with user password. The value must be a sequence composed of the following tokens:
-
print - Enables printing the document.
-
modify - Enables editing the document.
-
copy - Enables copying text and images from the document to the clipboard.
-
annotate - Enables adding notations to the document and changing the field values.
Tokens can be specified in any order, separated by commas and/or spaces.
Note:
If neither user password nor owner password is set, security is disabled and the rendered PDF is not encrypted.
If the user password is set and the owner password is not set, then the latter is set equal to the former. This enables password protection on the PDF file, but gives password holder full control over the document: no distinction is made between user and owner.
If the owner password is set and the user password is not set, the rendered PDF document can be viewed by anyone without entering a password. However, operations on this file will be restricted to privileges specified in the user privilege list; other operations will require authentication with the owner password.
Default: Security disabled (neither of the passwords are set). Default privilege list is annotate.
These features can also be controlled by the USERPASSWORD, OWNERPASSWORD, and USERPRIVILEGES options in the configuration file for the PDF generator.
Note:
Setting passwords through a configuration file poses obvious security risks, and is not recommended. Use processing instructions to enable file protection.
<?xep-postscript-language-level value?>This processing instruction sets target PostScript language level.
The following are possible values:
-
2
-
3
Note:
When the language level is set to 2, some advanced features and font flavours are not available.
Default: 3
This feature can also be controlled by the LANGUAGE_LEVEL option in the configuration file for the PostScript generator.
<?xep-postscript-clone-eps value?>This processing instruction controls whether EPS graphics are included in the PostScript output using forms mechanism, or by pasting their contents at each occurrence.
The following are possible values:
-
true - EPS graphics are pasted into the output stream at each occurrence. This may lead to a substantial growth of the resulting file size.
-
false - EPS graphics are in PostScript form. This minimizes the file size, however, some EPS images cannot be processed this way and it may corrupt the PostScript code.
Default: true
This feature can also be controlled by CLONE_EPS option in the configuration file for the PostScript generator.
<?xep-postscript-page-deviceentrynameentryvalue?>
This processing instruction sets a single entry
entryname in the page device dictionary to
value entryvalue. Entry name must be a
valid PostScript name (with or without leading slash). The value is
specified as an arbitrary PostScript expression. Entry name and value
must be separated by whitespace. There can be more than one such
instruction, each setting its entry.
Warning
XEP does not check the spelling of either the entry name or the value supplied in this instruction. Wrong code passed with this option can invalidate the whole output file.
To set page device options for the whole document, the
respective instructions should appear at the top of the document,
before the <fo:root> element. Such
entries are set in the document setup section and cleaned up in the
document trailer.
To control page device settings for a single page, the
instructions should be specified inside the <fo:simple-page-master> object used to
generate the page. In this case, page setup parameters are modified in
the page setup section and reset in the page trailer.
<?xep-postscript-page-label value?>This processing instruction changes the label argument of %%Page PostScript command. This PI should be inserted to fo:simple-page-master element.
The following are possible values:
-
value - Any text. The text may contain an optional token %d that will be automatically replaced with incrementing integer values, starting with 1.
Note:
Any time the document page contains xep-postscript-custom-comment Processing Instruction with value different to the previous one, the incrementing counter will be automatically reset to 1.
Default: blank
<?xep-postscript-custom-comment value?>This processing instruction allows inserting custom comments into PostScript document.
The following are possible values:
-
value - Any valid PostScript comment.
Note:
If the PI is inserted into fo:root element or before it, the value is placed in the document header, before %%EndComments. If the PI is inserted into fo:simple-page-master element, the value is placed in every page which uses this fo:simple-page-master as a template, after %%EndPageSetup comment. If the PI is inserted into fo:page-sequence element, the value will be placed for each page of the sequence, after %%EndPageSetup comment. The value will be validated before inserting to document, all "%" symbols will be removed, the first symbol will be capitalized and the value will be prepended with one (for page level comments) or two (for document level comments) "%" symbols.
Default: no comment.
<?xep-postscript-image-inline-threshold value?>This processing instruction controls the placement of images in PostScript document. Images that appear just a few times in a PostScript document are placed in Page Setup section of the pages where they are used, and not in Document Setup. This allows the printers to read image data when required, keep in memory for a short time, and safely flush it after the page is printed. In general, this feature allows to print larger documents.
The following are possible values:
-
value - An integer value greater or equal to -1.
Assuming the value is n, the behaviour of the PostScript backend is defined by the following rules:
-
If an image appears in the document more than n times, it goes to Document Setup.
-
If an image appears n times or less, it is placed in Page Setup on the page(s) where it is used.
-
The default value 0 makes all images be in Document Setup section. This is the old behaviour, equivalent to the absence of this option.
-
The value -1 makes all images be in Page Setup section.
Default: 0.
This feature can also be controlled by IMAGE_INLINE_THRESHOLD option in the configuration file for PostScript generator.
<?xep-out-embed-images value?>or, in case of SVG generator:
<?xep-svg-embed-images value?>This processing instruction controls whether the XML (SVG) output generator embeds external images referenced in the document in the resulting document instance as Base64 strings.
The following are possible values:
-
true - All images are stored inside the resulting file using the
data:URL scheme. -
false - Images are not embedded. In the generated XML file, images are referenced by their original URLs.
Default: false
This feature can also be controlled by the EMBED_IMAGES option in the configuration file for the XML output generator.
Fonts can be configured inside the <fonts> element. It contains descriptors for
font families, font groups, and font aliases. The formatter uses them to
map XSL-FO font properties to actual fonts.
Fonts are categorized into families, which is the basic
configuration unit in XEP, and then further into groups. A font family
is a set of fonts that share a common design but differ in stylistic
attributes, such as upright or italic, light or bold. All data
pertinent to one font family is contained inside a <font-family> element.
The <font-family> element contains the attribute
described in the following table:
Table 16. Font-Family Attributes
| Attribute | Possible Values | Description |
|---|---|---|
| name | free textNote:Family names must be unique within the configuration file. They are matched against the respective XSL-FO property value. |
Identifies the font family. |
When no font family is specified in the input file, the default
is defined by default-family
attribute of the <font> element. Its
value is a family name that must be present in the file, otherwise a
configuration error occurs.
The following is an example of a font family descriptor:
<font-family name="Courier">
<font>
<font-data afm="Courier.afm"/>
</font>
<font style="oblique">
<font-data afm="Courier-Oblique.afm"/>
</font>
<font weight="bold">
<font-data afm="Courier-Bold.afm"/>
</font>
<font weight="bold" style="oblique">
<font-data afm="Courier-BoldOblique.afm"/>
</font>
</font-family>Inside the family descriptor, there are one or more entries for
individual fonts that belong to the family. A font entry is specified
by a <font> element. It has
attributes to specify features of the font within the family, such as
weight, style, and variant. For a font to be selected by a
formatter, these attributes should match font-weight, font-style, and font-variant specified in the XSL-FO
document.
Most fonts can be either embedded into
the resulting PDF or PostScript document or specified as fonts
external to the file. If the font is external, the rendered file can
only be viewed on systems that have the font configured for use with
viewing or printing the application. Typically, all fonts are
embedded except for 14 standard Adobe PDF fonts. For some
applications, embedding basic fonts may also be required. Embedding
of a font is controlled by the embed attribute of the <font> element describing the font.
An embedded font can be subsetted, which
means that instead of storing the entire font in the document, XEP leaves
only those glyphs that are actually used in the
text. This option reduces the document size but makes it unsuitable
for subsequent editing. Subsetting is governed by the subset attribute of the <font> element.
To provide a more compact notation, the embed and subset properties are
inheritable down the configuration tree: when
specified on a node in the configuration file, they affect all
<font> descendants of that node.
For example, embed/subset attributes specified in <font-family> will affect all fonts in that
family; placing them on <font-group> will set the respective
parameters for all fonts in all families in the group (unless
overridden on some descendant node), etc.
XEP does not support embedding and subsetting of native AFP fonts in AFP documents so far.
Note:
TrueType and OpenType fonts may contain internal flags that prohibit their embedding or subsetting. XEP honors these flags and may refuse to embed or subset your font if the respective action is not authorized by the flags inside it.
To use an AFP font with XEP, it is necessary to obtain AFP font files containing Codepage and Charsets. An URL location to
the Codepage file should be specified in the codepage-file attribute of <font-family> element and attribute codepage-name should contain the name of corresponding Codepage. Font encoding can be specified in encoding attribute of <font-family> element (default value is Cp500).
The size (for raster AFP fonts) should be specified in the size attribute of the <font> element. URL to Charset file should be specified in charset-file attribute of <font-data> element and attribute charset-name should contain the name of Charset respectively.
Example: suppose we have a raster AFP font with Codepage file T1EDO500.CDP and Charset file C0V08000.CHS containing metrics for characters (size 10, italic). Its descriptor in the configuration file can look like this:
<font-family name="AfpFont"
codepage-name="T1EDO500"
codepage-file="T1EDO500.CDP"
encoding="Cp1146">
<font size="10" style="italic">
<font-data charset-name="C0V08000" charset-file="C0V08000.CHS"/>
</font>
...
</font-family>Algorithmic slanting can be applied to fonts in order to
produce oblique or backslanted versions of fonts that do not have
separate outlines for these styles. This is done by placing a
<transform> element inside the
<font> descriptor. The slant angle
is specified in the slant-angle
attribute on the <transform> node.
Its value sets the angle in degrees. Positive angles slant the text
clockwise, producing oblique versions; negative ones rotate it
counterclockwise, producing backslanted font styles.
XEP does not support algorithmic slanting of AFP fonts so far.
If a font family contains no entry for oblique or italic font style, the oblique font is produced algorithmically by applying a default slanting of 12°. Similarly, a missing backslant font is synthesized from the nearest upright version, slanting it by -12°.
Fonts can be instructed to contract certain sequences of
characters into ligatures. A set of ligature characters is specified
in the ligatures attribute of
the <font> element, as a space- or
comma-separated list of ligature characters. The characters must be
Unicode ligature codepoints.
Note:
In XEP, ligaturization support is basic: only ligatures registered in Unicode can be used. Moreover, ligaturization does not work for characters that undergo contextual shaping: this excludes all Arabic ligatures from consideration. Further versions of XEP are expected to improve ligaturization support.
Type 1 fonts may have different encoding tables. (Encoding table is an essential part of a Type 1 font and matches character codes to glyph names). According to PDF Spec, there are 3 predefined encodings: WinAnsi, MacRoman, and MacExpert. There is also the built-in font's encoding. All other encodings are treated as custom ones.
In Adobe Acrobat it is possible to see each Type 1 font encoding used in a document (Document Properties panel -> Fonts tab -> Encoding field for each Type 1 font). The value of this field may be one of:
-
Standard - The font's built-in encoding
-
Ansi - Windows Code Page 1252 (Windows ANSI)
-
Roman - Mac OS standard encoding for Latin text in Western writing systems
-
Expert - An encoding for use with expert fonts
-
Custom - A custom encoding
The same values (but 'Custom') may be used for
initial-encoding.
To provide a more compact notation, the initial-encoding is
inheritable down the configuration tree: when
specified on a node in the configuration file, it affects all
<font> descendants of that node.
For example, initial-encoding
attribute specified on <font-family>
will affect all fonts in that family; placing it on <font-group> will set the respective
parameter for all fonts in all families in the group (unless
overridden on some descendant node), etc.
Note:
This attribute only affects the first encoding table for a Type 1 font it is specified on. If the document contains glyps (from this font) that do not belong to the specified first encoding table, XEP will add more encoding tables which will all be treated as Custom.
Several font families can be wrapped into a <font-group> container element. Groups can be
nested, forming complex font hierarchies. This element does not affect
font mapping and serves only for logical grouping of font families.
In particular, it is often convenient to use it as a host for the xml:base property, to specify a common
base directory for a group of font families that form a package.
Another suggested use of <font-group> is for remoting: contents of the
font group can be placed into a separate file and reused across
multiple font configurations.
The only attribute specific to <font-group> is label, which assigns a name to the group.
The name serves only for record keeping, no constraints are imposed on
it.
XEP uses font aliases to provide alternate
names for font families and group several families into one “logical”
family. A font alias is defined by a <font-alias> element. The element has two
attributes, both required: name
is the name of the “logical” font family, and value is a comma-separated list of font
family names to which it should resolve. The list may contain a single
font family; in this case, the alias merely provides an alternate name
for it.
Note:
Aliases always resolve to “real” families and not to the other aliases. Chained alias resolution is not possible in XEP.
Language-specific configuration parameters are stored in the third
major section of the configuration file, inside a <languages> element. The <languages> element contains one or more
<language> elements, and each <language> element stores information pertaining to a
single language. The language is identified by two attributes:
-
name - The name of the language.
-
code - A list of codes used to refer to the language in the XSL-FO input data. Multiple codes are separated by spaces.
In XEP two kinds of data are configurable in this section of the configuration files:
-
Hyphenation patterns
-
Language-specific font aliases
XEP uses TEX hyphenation patterns for hyphenation data. Details on hyphenation algorithm are described in Appendix B.
A hyphenation pattern file is associated with a language by
placing a <hyphenation> element into
the language section in the configuration file. Its pattern attribute specifies the URL to the
TEX pattern file. An optional encoding attribute specifies the encoding
of the pattern file; if it is missing, ISO-8859-1 is assumed.
Language sections may also contain <font-alias> elements, described above in
the section called “Font Aliases”. These aliases are activated when the
language is selected in the input XSL-FO document; they take
precedence over aliases specified in the <fonts> section of the configuration file
and may mask them.
XEP can be configured to use a specific entity resolver
for all SAX parsing calls inside it.
The resolver class is specified by a Java system
property com.renderx.sax.entityresolver.
It must have a public constructor with no arguments,
and implement org.xml.sax.EntityResolver
interface.
Similarly, XEP can assign a user-defined class to resolve URIs
in calls to document() function,
<xsl:import>, and
<xsl:include> XSLT directives.
The class name is specified in com.renderx.jaxp.uriresolver
system property; it must provide a public default constructor, and implement
javax.xml.transform.URIResolver interface.
The principal use of these features is to add support for XML catalogs to XEP, to avoid repeated loading of common DTDs and stylesheets from the internet. For example, the following setting configures XEP to use XML entity and URI resolver from Apache project (provided that you have included resolver classes in the classpath, and properly configured it):
java -Dcom.renderx.sax.entityresolver=org.apache.xml.resolver.tools.CatalogResolver -Dcom.renderx.jaxp.uriresolver=org.apache.xml.resolver.tools.CatalogResolver …
XML catalogs resolver is included into xml-commons tools available as a part of Apache project. For further information about catalogs and entity resolution, and for resolver download please proceed to Apache website: http://xml.apache.org/commons/components/resolver/index.html.
This section contains the following topics:
AFP documents can be generated through the following:
-
XEP Assistant - When formatting the XML file using the XEP Assistant, select AFP as the format, as described in XEP Assistant.
-
Command Line - Using the command line, AFP documents as well as AFP resource files can be generated.
-
To generate an AFP document, use the parameter -afp:
-afp <afp document file name>
For more information, please refer to Using the Command Line.
-
To generate an AFP resource file, use the parameter -DH4AFP.RESOURCE:
-DH4AFP.RESOURCE=<afp resource file name>
Note:
Since -DH4AFP.RESOURCE is a generator option parameter, it must precede all other parameters like -xml, -xsl, -fo, -xep, -pdf, -ps, -afp, -svg.
Alternatively, you can use the configuration file variable. For more details, refer to the section called “Configuring the XEP AFP Generator”.
-
Non-CID OTF fonts are currently supported which allows for higher AFP standard conformance. Fonts larger than 36 pt can be processed as well, which produces better AFP documents.
XEP supports two different ways using fonts in AFP generator:
-
The first variant is based on native Non-CID Open Type Fonts (OTF) that correspond F:OCA specifications. It is described in section the section called “Supported AFP Fonts”. This variant requires a set of native AFP font files and allows using native AFP fonts metrics.
You may also find useful information on the section called “AFP Fonts”.
-
Another variant of configuration lets to map AFP native fonts to non-AFP fonts supported by XEP to obtain font metrics. In this case, the metrics of TrueType/OpenType fonts are used for formatting; after that, when generating AFPDS stream, XEP uses mapped font values to refer in result document.
Therefore, AFP generator for XEP supports all kinds of fonts supported by XEP.
Mapping FO fonts and native AFP fonts can be configured in the XEP configuration file, in the AFP generator configuration section. Please refer to the section called “Configuring Fonts” for details.
Raster image formats are not supported by AFP, and color images are rarely supported by AFP printing systems. Therefore, depending on the configuration options, all raster images are either converted to bi-level images or grayscale images.
| Image | Properties |
|---|---|
| Bi-level images | 1 bit per pixel, compressed |
| Grayscale images | 8 bits per pixel, uncompressed |
Note:
In AFP, bi-level images are mixed with their background. Therefore, white points appear transparent.
Images can be included once, and referenced multiple times. This allows for reduced output size and improved performance. This feature is very useful for repeating images, like corporate logos, headers, footers, etc.
The image can be included in the main AFP output file, or in a separate resource file as described in the section called “Other Configuration Options”.
If a source document refers to an image, and the image is bigger than the containing block, normally it should be clipped. AFP Backend correctly clips only those images having resolution equal to (or higher than) the AFP document's resolution. Otherwise, the entire image appears, probably overlapping with other page elements positioned to the right or below the image container.
Highlight color is a special case of color encoding, when a solid colorant used (contrary to other schemes like RGB, CMYK, etc). In XSL-FO, this kind of encoding is called Spot Color. XEP AFP Backend treats spot color in source document and produces AFP Highlight Color instructions within the MO:DCA-P stream.
Highlight Color has the following major attributes:
-
Colorant name - usually, includes colorant vendor name and catalogue ID of the color. For example, "PANTONE Orange 021 M".
-
Tint - percentage of colorant covering target area. AFP printers are capable to cover certain percentage of target area, making the color opaque.
Each value must be given either in percents (from 0% to 100%) or as a number in the interval from 0 to 1.
Note:
When the Highlight Color space is specified in a target repeating group, the percent coverage parameter is normally supported only for areas such as object areas and graphic fill areas. For other data types this parameter is normally simulated with 100% coverage.
-
Shading - besides tint, AFP devices are capable to cover certain percentage with main color (usually Black). This attribute defines which percentage will be covered with main color.
-
Alt (alternative) color - used in XSL-FO to define most-close analogue to Spot Color. This can be either CMYK, RGB, or Grayscale value.
AFP Generator uses the following algorithm of Spot Colors identification:
-
AFP Backend for XEP finds spot-color in source document. It looks up the configuration file for Highlight Color Index defined within.
-
If Colorant ID found, AFP Backend uses the ID associated.
-
Otherwise (Colorant ID not found), AFP Backend registers the Highlight Color within the range of Custom Colors defined in MO:DCA (ID 0x0100-0xFF00).
-
Next time spot-color with same colorant used within the same document, it will obtain the same ID. Automatically obtained ID's are not saved for further use after the operation is completed.
Scalable Vector Graphics (SVG) is a language for describing two-dimensional vector graphics in XML.
AFP Backend 4.14 has limited support of SVG primitives. They are rendered as instructions listed within G:OCA command set.
The following G:OCA objects are currently supported:
-
Lines (svg:line).
Lines are considered to be strokes of a pen that draws on the canvas.
The size, color, and style of the pen stroke are part of the line's presentation. These characteristics are in the style attribute.
Currently
"stroke"(color of line) and"stroke-width"(width of line) characteristics of Style attribute are supported.For example:
<svg:line x1="20" x2="20" y1="62" y2="8" style="stroke-width:6; stroke: blue;"/> -
Rectangles.
The interior of the rectangle can be filled with the specified fill color.
If a fill color was not specified, the interior of the shape will be filled with white.
The outline of the rectangle is drawn with strokes, whose characteristics can be specified by the same way as for lines.
"fill"(fill color),"stroke"(outline color) and"stroke-width"(width of outline) attributes are supported.If the fill color specified as "none", then only outline of the rectangle will be drawn with color specified in "stroke" attribute.
For example:
<rect x="60" y="60" width="80" height="70" fill="none" stroke="yellow" stroke-width="5"/> -
Paths.
Paths represent the geometry of the outline of an object, defined in terms of
<moveto>(set a new current point), lineto (draw a straight line), curveto (draw a curve using a cubic Bézier), arc (elliptical or circular arc), and closepath (close the current shape by drawing a line to the last moveto) elements.Full implementation of Path processing has been made.
Supported commands:
-
The
"moveto"command.The "moveto" commands (M or m) establish a new current point.
-
The
"closepath"command.The "closepath" (Z or z) ends the current subpath and causes an automatic straight line to be drawn from the current point to the initial point of the current subpath.
-
The
"lineto"commands.The various "lineto" commands (L, l, H, h, V, v) draw straight lines from the current point to a new point.
-
Cubic Bézier curves (C, c, S and s).
A cubic Bézier segment is defined by a start point, an end point, and two control points.
Also includes filled areas with border in form of Bézier curve.
-
Quadratic Bézier curves (Q, q, T and t).
A quadratic Bézier segment is defined by a start point, an end point, and one control point.
Also includes filled areas with border in form of Bézier curve.
-
Ellipstical arcs (A and a).
An elliptical arc segment draws a segment of an ellipse. Various kinds of elliptical arcs are supported.
Note:
Internally, XEP transforms all arcs to Bézier curves.Also includes filled areas with border in form of arc.
-
Filled areas may be formed by any combination of lines, arcs, and Bézier curves. AFP Generator correctly processes such case
of svg:path and makes areas filled correctly.
Coordinate system transformations are also supported.
A new user space can be established by specifying transformations in the form of a "transform" attribute on a container element
or graphics element or "viewBox" attribute on an "svg", "symbol", "marker", "pattern" and the "view" element.
The "transform" and "viewBox" attributes transform user space coordinates and lengths on sibling attributes on the given element and all of its descendants.
The following logic elements are currently supported:
-
Groups (
svg:g). -
Rotation of SVG block.
<fo:block-container reference-orientation="270">
Possible values are:
"0","90","180", and"270". -
Nested SVG (
svg:svg) and Viewbox (svg:viewbox) are supported.Partial implementation of
"transform"and"viewBox"attributes processing has been made.Transformations can be nested, in which case the effect of the transformations are cumulative.
-
SVG text.
XEP has limited support of SVG text. Only raster fonts are supported.
If SVG text is enclosed into viewbox, the actual font size is calculated accordingly.
In the following sample, SVG block is stretched 2 times by X and Y axis, and font of size 10 is used.
<svg:svg width="400" height="100" viewBox="0 0 200 50"> <svg:text style="font-family:Helvetica; font-size:10; font-weight:bold" text-anchor="middle" x="100" y="25"> Sample </svg:text> </svg:svg>
The actual font size will be equal to 20.
If viewbox zoom factors by X and Y axis are different, root-mean-square value for font size is used.
In the following sample, SVG block is stretched 3 times by X axis and remain the same by Y axis.
<svg:svg width="600" height="50" viewBox="0 0 200 50"> <svg:text style="font-family:Helvetica; font-size:10; font-weight:bold" text-anchor="middle" x="100" y="25"> Sample </svg:text> </svg:svg>
The actual font size will be calculated as original_size * square_root((zoomX^2 + zoomY^2)/2) and equal to 22.
For SVG text, only the following rotation values are possible:
"0","90","180", and"270". Nested rotations of svg blocks and viewbox are supported. -
Markers.
The "marker" element defines the graphics that is to be used for drawing arrowheads or polymarkers on a given "path", "line", "polyline" or "polygon" element.
Not supported or limited support:
-
Gradient fill for rectangles is not supported: solid fill color used.
-
Other primitives not listed above are not supported by current version.
A barcode is a machine-readable representation of information in a visual format.
Most types of barcodes stores data in the width and spacings of printed parallel lines.
Barcodes are simple to represent as black rectangles separated by white spaces, but they have proved to be difficult to generate accurately. Bar and space widths are often computed in a complex manner and checking digits additionally complicates the process.
AFP Backend uses XSLT stylesheets to implement the computational part and SVG to draw the image and text. These stylesheets are available for free download from RenderX site:
http://www.renderx.com/demos/barcodes.html
As soon as XSL-FO 1.0 does not have native support of barcodes, technical implementation of them is based on SVG. These stylesheets
render barcodes as SVG primitives, including additional <desc> tag containing the value and parameters of barcode rendered.
AFP Backend processes this tag and decides whether it is barcode or another SVG graphic.
If barcode tag is found, the barcode is rendered with BC:OCA or G:OCA, depending on which is enabled. This is done with USE_BCOCA_LEVEL and USE_GOCA_LEVEL configuration parameters. If both BC:OCA and G:OCA are enabled, BC:OCA overrides. Please refer configuration parameters section about configuring BC:OCA and G:OCA.
Please refer the section called “Graphics Support” section for more information about G:OCA implementation.
Note:
AFP Barcodes (BC:OCA) are verified to be compatible with barcodes generated by WordML2FO stylesheets (the latest version). RenderX WordML2FO stylesheets are available for free download from RenderX site:
Currently, the following types of Barcodes are supported by AFP Backend:
-
EAN-13
-
EAN-8
-
UPC-A
-
Codabar
-
Code2of5
-
Code3of9 (with limitations)
-
Code128 (with limitations)
-
4state-AU (with limitations)
Please refer the section called “Limitations of the XEP AFP Generator” for more details.
For example:
<svg:svg xmlns:svg="http://www.w3.org/2000/svg"
width="34.98mm" height="27.39mm">
<desc xmlns:mydoc="http://example.org/mydoc">
<barcode value="9780444505156" type="EAN-13"/>
</desc>
<svg:rect y="0" height="24.915mm" x="3.63mm"
width="0.33mm" style="fill: black;"/>
<svg:rect y="0" height="24.915mm" x="4.29mm"
width="0.33mm" style="fill: black;"/>
...
<svg:rect y="0" height="23.1mm" x="4.95mm"
width="0.99mm" style="fill: black;"/>
</svg:svg>
<desc/> tag must have single child node <barcode/>. The following attributes are available for <barcode/> tag:
-
value contains string value of the barcode
-
type one of the values listed in supported types:
-
EAN-13
-
EAN-8
-
UPC-A
-
Codabar
-
Code2of5
-
Code3of9
-
Code128
-
4state-AU
-
Note:
If you develop custom stylesheets implementing Barcodes, please note that barcode MUST be alone item within SVG block if barcodes
are generated with BC:OCA. That is, AFP Generator skips SVG content after <desc> tag.
FORMDEF is the AFP 'forms definition.' It defines the parameters of the physical page environment. The parameters including the following:
-
Paper size and rotation.
-
Simplex or duplex printing mode.
-
Printing several logical document pages on the same sheet.
-
Number of copies.
-
Paper cutting, punching, etc.
-
Paper source selection.
-
Overlays for physical and logical pages.
-
Finishing documents.
FORMDEF can be attached to a single document, or to multiple documents. It is contained in the resource section of a printfile.
Note:
The XEP AFP Generator has limited support for generation of FORMDEF resources. In general, complex features like overlays and page segments are not supported.
FORMDEF is a MO:DCA resource. Therefore, two steps are required in order to generate a document with FORMDEF.
-
You must specify the resource file on the XEP command line.
-
You must concatenate the resource file and the document file or files, in order to form a print file.
Note:
If a resource file is not specified, the FORMDEF instructions are processed but not generated in the resulting AFP file.
FORMDEF resource is described in the source document as a set of special processing instructions. These instructions may appear at the top of the XSL-FO document before or after the <fo:root> element ,or within page masters. Each processing instruction has a pseudo-element which is commonly used in XML similar to an <?xml ?> instruction.
FORMDEF processing instructions are divided into two main groups:
-
Non-repeating instructions - They may only have one instance within a document.
The following are non-repeating instructions:
-
xep-afp-form-definition
-
-
Repeating instructions - They may appear in a document multiple times.
The following are repeating instructions:
-
xep-afp-page-definition
-
xep-afp-copy-group
Repeating instructions contain a pseudo-element "id," which uniquely identifies each instance of an instruction of the same type within a document. When XEP processes repeating instructions, only the first instance of an instruction of the id is processed. All other instructions with the same id are ignored. If an instruction is inside a page master, it is reproduced on each page generated by this page master, but XEP processes only the first occurrence of this instruction, as instruction ids are same.
-
The syntax and semantics of FORMDEF processing instructions are as follows:
-
xep-afp-form-definition - Defines the FORMDEF resource.
Format:
<?xep-afp-form-definition sheet-height="size-value" sheet-width="size-value"?>
Attributes:
-
sheet-height - Defines the sheet height. Values may contain simple size expressions such as, "3in" or "10pt."
-
sheet-width - Defines the sheet width. Values may contain simple size expressions such as, "3in" or "10pt."
Both sheet-height and sheet-width are mandatory attributes.
-
-
xep-afp-page-definition - Defines a logical page on a sheet of paper or other medium.
Format:
<?xep-afp-page-definition id="id-number" x0=" size-value" y0="size-value" orientation="ori-value" type="type-value"?>
Attributes:
-
id - Instruction identifier. The value must be a decimal number.
-
x0, y0 - The coordinates of the logical page presentation on a physical sheet. Values may contain simple size expressions.
-
orientation - The orientation of the logical page on a physical sheet. Possible values are 0, 90, 180, or 270.
-
type - The type of logical page which defines the common page layout. Possible values are the following:
default-front-page, default-back-page, p1-front-page, p1-back-page, p2-front-page, p2-back-page, p3-front-page, p3-back-page, p4-front-page, p4-back-page, default-front, default-back, p1-front, p1-back, p2-front, p2-back, p3-front, p3-back, p4-front, p4-back
-
-
xep-afp-copy-group - Defines a copy group as well as its attributes and keywords.
Format:
<?xep-afp-copy-group id="id-number" copy-count="number" mode="mode-val" [key="value"]* ?>
Attributes:
-
id - Instruction identifier. The value must be a decimal number.
-
copy-count - The number of copies in the copy group. The value must be a decimal number.
-
mode - Printing mode. Possible values are simplex, duplex, and tumble-duplex.
id, copy-count and bold are mandatory attributes.
xep-afp-copy-group may contain several optional pairs of keywords and values. Each keyword-value pair must conform to the following rules:
Format of key-value pair:
key-value-pair = key, '=', '"', value, '"';
key = ( 'x' | 'X' ) , ('0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F'), ('0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F');value = ('0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F'), ('0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F');Examples of valid keys: "x12", "XFF", "xA1".
Examples of valid values: "AF", "15", "FD".
Each key-value pair adds a keyword with value to MO:DCA MMC structured field content.
Note:
Printing mode such as simplex, duplex or tumble duplex is controlled separately by the mode attribute which effectively generates XF4 MMC keyword. If the mode of printing is duplex, the copy group is generated twice in MCC automatically, and you do not need to repeat the group twice. You need not use XF4 MMC keyword explicitly.
-
Configuration of the AFP generator is performed in a usual way all XEP generators are configured. All configuration options for AFP generator are child elements of XEP configuration file element <generator-options format="AFP">. Each AFP generator configuration option is an element option and looks like
<option name="OPTION_NAME" value="OPTION_VALUE"/>.
Note:
AFP parameters can be set in three different ways, depending on your specific needs:
-
Configuration file - in this case, the parameter value applies to all documents processed with this configuration file.
-
Environment variable (Generator option) - passed within command line and applies for current run of XEP. Generator option value overrides Configuration file values.
-
Processing Instruction - passed within Processing Instruction (PI) inside XSL:FO document. Please refer Output Format Settings section for more details on processing instructions. Processing Instruction value overrides Generator option and Configuration file values.
In this section, all parameters will be described in Configuration file format.
AFP generator's prefix for Generator options is H4AFP. So, RESOLUTION parameter will look like this:
-DH4AFP.RESOLUTION=1440
AFP generator's prefix for Processing instructions is xep-afp-. So, RESOLUTION parameter will look like this:
<?xep-afp-resolution 1440?>
Processing Instruction may appear at document level or page level. Every time the page level parameter is set, it applies until the same parameter is set to another value. For example, if RESOLUTION option is set to: 1440 in config file; to 720 for page #5; and to 1440 for page #10 - the value of 720 will apply for ALL pages ##5 till 9.
AFP generator for XEP has extended support for international Character sets. The following chapter describes how to configure the necessary character sets and corresponding Codepages.
One should configure only those Character sets and Codepages supported by the fonts residing in target AFP device.
Note:
Even if the printer is configured to support various Codepages, it is still reasonable to remove from XEP configuration file these Character sets not used in the documents to improve performance.
The element <charsets> is a container for Character sets configuration.
Each Character set is configured within <charset> element. It has the attribute name describing the name of Character set. The attribute name must be unique.
Character set definition contains the following child elements:
-
List of Unicode character ranges applying the Character set, represented
<code-ranges>element; -
List of specially mapped characters, represented by
<character-mapping>element; -
Single
<codepage>element defining the Unicode to Codepage mapping;
Unicode character range is defined by by <code-range> element. It has the following attributes:
-
fromandtodefining beginning and ending values of Unicode characters belonging to the character range; Must be hexadecimal value; Required;
Codepages are defined by by <codepage> element. It has the following attributes:
-
namestring value defining Java standard name of Codepage; In Java environment, there must be a registered charset provider with the given name; Required; -
ibm-namestring value defining AFP codepage specification ("Txxxxxxx"); Required; -
forcelatina boolean (true or false) value defining whether the codepage contain Base Latin characters in lower half of code bytes (0x00..0x7F); Optional; Default=true; -
descproviding text description of the code page; Optional;
Specially mapped characters are defined by by <character> element. It has the following attributes:
-
unicodedefining two-byte hexadecimal value of specially mapped character; Required; -
afpdefining one-byte hexadecimal value of mapped character within target Codepage; Required; -
descproviding text description of the character; Optional;
Note:
All the remaining characters belonging to Unicode character ranges and not listed with <character> elements, are translated to target Codepage using Java standard mechanisms of string translations;
Please refer the section called “International Character Set Support” section to find more details on how the AFP generator works with Unicode ranges and Codepages.
The following example demonstrates how to configure necessary Character sets for AFP generator:
<generator-options format="AFP">
<charsets>
<!--languages-->
<charset name="Latin">
<code-range from="0x0000" to="0x007F"/>
<codepage name="Cp500" ibm-name="T1V10500" forcelatin="true" desc="Base Latin"/>
</charset>
<charset name="Latin_1">
<code-range from="0x0080" to="0x00FF"/>
<codepage name="Cp819" ibm-name="T1000819" forcelatin="true" desc="Latin_1"/>
</charset>
<charset name="Cyrillic">
<code-range from="0x0400" to="0x04FF"/>
<codepage name="Cp866" ibm-name="T1000866" forcelatin="true" desc="ANSI Cyrillic"/>
</charset>
<charset name="Chinese">
<code-range from="0x4E00" to="0x9FFF"/>
<codepage name="Cp950" ibm-name="T1094700" forcelatin="false" desc="Chinese"/>
</charset>
<charset name="Hebrew">
<code-ranges>
<code-range from="0x0590" to="0x05FF"/>
</code-ranges>
<codepage name="Cp424" ibm-name="T1000424" forcelatin="true" desc="Hebrew"/>
</charset>
<charset name="Greek">
<code-ranges>
<code-range from="0x0370" to="0x03ff"/>
</code-ranges>
<codepage name="Cp875" ibm-name="T1000875" forcelatin="false"/>
</charset>
<!--symbol-->
<charset name="Symbols00259">
<code-ranges>
<code-range from="0x03C0" to="0x03C0"/>
<code-range from="0x2020" to="0x2020"/>
<code-range from="0x003C" to="0x003C"/>
<code-range from="0x02C6" to="0x02C6"/>
<code-range from="0x00B0" to="0x00B0"/>
<code-range from="0x25CF" to="0x25CF"/>
<code-range from="0x25C6" to="0x25C6"/>
<code-range from="0x25A1" to="0x25A1"/>
<code-range from="0x2341" to="0x2341"/>
<code-range from="0x25BA" to="0x25BA"/>
</code-ranges>
<character-mapping>
<character unicode="0x03C0" afp="0x46" desc="pi small"/>
<character unicode="0x2020" afp="0x4b" desc="dagger"/>
<character unicode="0x003C" afp="0x4c" desc="less"/>
<character unicode="0x02C6" afp="0x5f" desc="circumflex accent"/>
<character unicode="0x00B0" afp="0x7c" desc="degree symbol"/>
<character unicode="0x25CF" afp="0xbc" desc="large bullet"/>
<character unicode="0x25A1" afp="0xda" desc="open square"/>
</character-mapping>
<codepage name="Cp259" ibm-name="T1000259" forcelatin="false"/>
</charset>
<charset name="Cp437">
<code-ranges>
<code-range from="0x2022" to="0x2022"/>
<code-range from="0x266A" to="0x266A"/>
</code-ranges>
<character-mapping>
<character unicode="0x266a" afp="0x0d" desc="musical note"/>
<character unicode="0x2022" afp="0x07" desc="bullet"/>
</character-mapping>
<codepage name="Cp437" ibm-name="T1000437" forcelatin="false"/>
</charset>
<charset name="Cp423">
<code-ranges>
<code-range from="0x03CA" to="0x03CA"/>
</code-ranges>
<character-mapping>
<character unicode="0x03CA" afp="0xb4" desc="acute accent"/>
</character-mapping>
<codepage name="Cp423" ibm-name="T1000423" forcelatin="false"/>
</charset>
<charset name="APL Graphic Escape">
<code-ranges>
<code-range from="0x25CA" to="0x25CA"/>
<code-range from="0x25A0" to="0x25A0"/>
<code-range from="0x203E" to="0x203E"/>
</code-ranges>
<character-mapping>
<character unicode="0x25CA" afp="0x70" desc="acute accent"/>
<character unicode="0x25A0" afp="0xC3" desc="down caret"/>
<character unicode="0x203E" afp="0xA0" desc="overbar"/>
</character-mapping>
<codepage name="Cp310" ibm-name="T1000310" forcelatin="true"/>
</charset>
</charsets>
</generator-options>Note:
Due to the nature of Character set configuration, it must be specified in xep.xml configuration file only and cannot be specified or overridden neither in command line parameters nor processing instructions
within the XSL-FO document.
-
AFPFont options are used for mapping XSL FO fonts to AFP fonts.
Each AFPFont option name starts with "AFPFont" and after a comma contains face name of a XSL FO font. Each AFPFont option value contains a list of nine subvalues separated with commas.
Example:
<option name="AFPFont,Helvetica" value="C0H200.0, C0H300.0, C0H400.0, C0H500.0, C0H201.0, C0H301.0, C0H401.0, C0H501.0, 278"/>
Subvalues in the list have following meaning:
-
AFP substitution font for font-weight="normal" font-style="normal"
-
AFP substitution font for font-weight="normal" font-style="italic"
-
AFP substitution font for font-weight="bold" font-style="normal"
-
AFP substitution font for font-weight="bold" font-style="italic"
-
AFP substitution font for symbolic subset and font-weight="normal" font-style="normal"
-
AFP substitution font for symbolic subset and font-weight="normal" font-style="italic"
-
AFP substitution font for symbolic subset and font-weight="bold" font-style="normal"
-
AFP substitution font for symbolic subset and font-weight="bold" font-style="italic"
-
Word spacing value in font relative units (please reference AFP FOCA reference for details)
Note:
If the font is not found within the table above, AFP Generator uses Helvetica to substitute. -
HighlightColor option is used for configuring mapping of colorant to Highlight Color ID within the target AFP device.
Each HighlightColor option starts with "HighlightColor" prefix and after comma should contain Color ID (hex or decimal). Value contains symbolic name of colorant.
Example:
<option name="highlightcolor,0x301" value="PANTONE Orange 021 M" />
or (the same)
<option name="highlightcolor,769" value="PANTONE Orange 021 M" />
-
USE_SHADING_PATTERNS specifies whether grayscale-filled areas should be filled with bi-level pattern. Percentage rate of containing black points will be close to required grayscale value.
1ortrueoryes- Shading patterns will be used0orfalseorno- Shading patterns will not be used (default)Example:
<option name="USE_SHADING_PATTERNS" value="yes"/>
Shading patterns work for rectangular areas only.
Shading patterns are limited for only those areas filled with grayscale color.
There are several patterns hard-coded into AFP backend: 0%, 3.125%, 6.25%, 10%, 12.5%, 20%, 25%, 30%, 37.5%, 40%, 50%, 60%, 62.5%, 70%, 75%, 80%, 87.5%, 90%, 95%, and 100%. If greyscale value does not exactly match any of listed values, the closest match will be used.
Shading patterns, as all bilevel images, are mixed with their background. Their white points appear transparent.
-
USE_REPLICATE_AND_TRIM specifies if "replicate-and-trim" feature will be used for shading patterns.
1ortrueoryes- "replicate-and-trim" is used0orfalseorno- "replicate-and-trim" is not used (default)If set to "
no", shading pattern raster image will be created for entire dimensions of rectangle. If set to "yes", only 8x8 pixels image will be created. Thus, this feature significantly reduces size of documents with shading patterns enabled, and produces best quality.Example:
<option name="USE_REPLICATE_AND_TRIM" value="yes"/>
This option applies only if USE_SHADING_PATTERNS equals to
true."Replicate-and-trim" feature is not supported by every AFP device, so it should be turned
offfor older printers without support of this feature. -
SHADING_PATTERN_RESOLUTION defines zoom factor for shading pattern raster.
(Default: 1.0)
Can contain any positive decimal value greater than
0and no greater than1Example:
<option name="SHADING_PATTERN_RESOLUTION" value="0.25"/>
Shading pattern raster image size is limited to 32kbytes. Thus, if the resolution is set high, it may exceed this limit. To avoid this, SHADING_PATTERN_RESOLUTION defines divider for actual raster size. For example, if rectangle area size is 1000x1000 px and SHADING_PATTERN_RESOLUTION is set to
0.25(25%), AFP Backend will produce raster image of size 250*250, and command AFP to stretch it to required dimensions. Note that quality of0.25(1/4) will produce raster image 16 times smaller.This option applies only if USE_SHADING_PATTERNS equals to
trueand USE_REPLICATE_AND_TRIM equals tofalse. -
TRY_USING_TIFF_COMPRESSION option allows the user to specify whether AFP backend attempts to compress shading patterns raster images with TIFF encoding.
1ortrueoryes- AFP Backend attempts to compress shading pattern rasters (default)0orfalseorno- AFP Backend does not attempt to compress shading pattern rastersExample:
<option name="TRY_USING_TIFF_COMPRESSION" value="yes"/>
Some rasters cannot be compressed with TIFF. In this case, uncompressed raster image is sent to output. Hard-coded rasters are known to be compressible or not, so AFP Backend does not try to compress uncompressible ones.
The only reason to set this value to "
no" is when your AFP device does not support TIFF compression.This option applies only if USE_SHADING_PATTERNS equals to
trueand USE_REPLICATE_AND_TRIM equals tofalse.
-
AFPLogLevel option lets users turn on output of additional information related to internal details of processing document elements in AFP generator. This information has various levels of detail, from 0 to 2.
0- AFP logging is turned off (default)1- AFP generator prints only warnings2- AFP generator prints warnings and information messagesExample:
<option name="AFPLogLevel" value="0"/>
-
RESOURCE option lets users turn on generating AFP resources (images, graphics, etc.) into separate resource file. If specified, this option should target to particular file name. If omitted, all resources are put within the main AFP output document
Default: (empty string)
Example:
<option name="RESOURCE" value="myresourcefile.afp.res"/>
Resource file is always rewritten.
-
RESOLUTION defines which document resolution will be output within the document. It must be positive integer value supported by target AFP device.
Default: 1440
Example:
<option name="RESOLUTION" value="1440"/>
-
AFPGrayImage option, if set to
yes, turns on embedding of raster images as grayscale images, 8 bit per pixel, uncompressed.1ortrueoryes- embed raster images as 8 bit0orfalseorno- embed raster images in their original format (default)Example:
<option name="AFPGrayImage" value="no"/>
-
USE_PTOCA_LEVEL defines maximal level of PT:OCA commands subset.
1- Use PT1 only (default)2- Use PT1 and PT2 only3- Use PT1, PT2, and PT3 subsetsExample:
<option name="USE_PTOCA_LEVEL" value="3"/>
Different AFP-capable devices support different command subsets. In order to comply with this difference and provide maximum compatibility while keeping highest quality and performance, this option must be set according current printer capabilities.
Please refer Presentation Text Object Content Architecture Reference for more details on specific commands belonging to various PT:OCA subsets.
-
USE_GOCA_LEVEL defines maximal level of G:OCA commands subset.
0- Do not use G:OCA commands (default)1- Use Level 1 only3- Use Levels 1 and 3Example:
<option name="USE_GOCA_LEVEL" value="1"/>
Different AFP-capable devices may or may not support G:OCA command subsets. In order to provide maximum compatibility, this option must be set according current printer capabilities.
Please refer the section called “Graphics Support” for more details on G:OCA implementation in XEP AFP Generator.
-
USE_BCOCA_LEVEL defines maximal level of BC:OCA commands subset.
0- Do not use BC:OCA commands (default)1- Use Level 1 onlyExample:
<option name="USE_BCOCA_LEVEL" value="1"/>
Set this parameter to
1in order to enable generating BC:OCA data within output stream.Please refer the section called “Barcodes Support” for more details on supported barcode types and barcodes implementation notes in XEP AFP Generator.
AFP Backend supports several ways to produce bulleted text.
-
Using external image
In order to use image approach, you should define <fo:list-item-label> section as in sample below (assuming you have bullet.png file in the same folder with FO file):
<fo:list-item-label end-indent="label-end()"> <fo:block> <fo:external-graphic src="url(bullet.png)" content-height="100%" content-width="100%"/> </fo:block> </fo:list-item-label> -
Using special Unicode symbol.
A special symbol can be used, like in sample below:
<fo:list-item-label end-indent="label-end()"> <fo:block>°</fo:block> </fo:list-item-label>
Note:
Unicode character used for text bullets must belong to any of Character Sets configured. The most common Unicode characters
0x2022and0x2023used for circle and triangle bullets belong to General Punctuation Unicode Character Set. -
Using SVG primitive
SVG opens bigger variety of possible bullets. This may include circles, diamonds, stars, and other shapes (filled and not filled ones). They also can be enchanced with effects like shadows, outline, and more.
Here is an example of plain filled square bullet using SVG:
<fo:list-item-label start-indent="18pt" text-indent="0pt"> <fo:block> <fo:instream-foreign-object display-align="center"> <svg:svg width="6pt" height="6pt"> <svg:rect x="1" y="1" width="5pt" height="5pt" fill="black"/> </svg:svg> </fo:instream-foreign-object> </fo:block> </fo:list-item-label>
Other approaches have not been tested and are not supported. Please refer the section called “Limitations of the XEP AFP Generator” for more details.
AFP Generator for XEP has multilanguage support. For each character in text blocks, it detects Character Set the character belongs to (out of character sets listed in configuration file). After that, it uses conversion table to convert the character to the CodePage that AFP device is capable to process.
Here is the description how AFP generator for XEP finds out which Codepage to use.
The source Unicode string is analyzed by characters.
For each of them, AFP generator determines Character Set (<character> element in config file) the character belongs to
(using the Code Ranges listed in configuration file specified in <code-range> elements).
If the range not found, the first configured range is assumed (normally, Base Latin).
After the range is found, AFP generator checks whether the character is specified within the list of specially translated
characters (<character-mapping> element).
If so, the character is translated according to the mapping table (afp attribute).
If not, AFP generator uses Java libraries to map the character to the corresponding code page (<codepage> element, (name attribute).
After that, it determines if the character belongs the same code page as the previous one in the same text block. For instance,
Chinese and Cyrillic characters cannot reside in the same AFP tect block due to different encodings.
However, Base Latin may follow the Cyrillic character since Cyrillic code pages usually contain Latin characters in lower
half of codes (0x00-0x7F).
This approach is determined by forcelatin attribute.
Finally, after the string of the same code page is composed, it becomes assigned with IBM encoded name (ibm-name attribute) and placed to AFPDS stream.
Note:
The number of Character ranges makes significant impact on the above logic performance.
Moreover, even if some characters of the documents will fall into wrong Character Set, they may not be printed in case if the AFP device does not support corresponding code pages.
So, it is strongly recommended to remove unused Character Sets from configuration file in order to obtain best results and productivity.
Note:
PT:OCA bullets seem to be very fast and effective solution, however it strongly depends on the fonts uploaded to the AFP device. So it requires careful attention configuring PT:OCA bullets against the particular target device.
The complete list of Unicode character sets can be found at W3C Web site. Here is the list of most common Unicode Character sets:
| Name | AFP CodePage | Text CodePage | Unicode Characters Range | Comment |
|---|---|---|---|---|
| Basic Latin | T1V10500 | Cp500 | 0x0000-0x007F | Basic Latin is automatically included into all character sets |
| Latin-1 | T1000819 | Cp819 | 0x0080-0x00FF | Contains umlaut characters for Western-European languages |
| Hebrew | T1000424 | Cp424 | 0x0590-0x05FF | Contains characters for Hebrew |
| Greek/Coptic | T1000875 | Cp875 | 0x0370-0x03FF | Contains characters for Greek language |
| Cyrillic | T1000866 | Cp866 | 0x0400-0x04FF | Contains characters for Cyrillic languages |
| Chinese | T1094700 | Cp950 | 0x4E00-0x9FFF | Contains characters for Chinese language (simplified) |
Please refer the section called “Configuring Character Sets” for more details.
-
AFP generator uses precision of 1/20 of point so its precision is 50 times worse than in other XEP backends.
-
AFP generator has limited support of SVG images. For more information about G:OCA implementation please refer the section called “Graphics Support”.
-
AFP generator does not support lines with styles other than
solid,dashed, anddotted; all other lines looksolidin generated AFP documents. -
AFP generator does not support SVG/G:OCA lines with style other than
solid; all lines looksolidin generated AFP documents. -
AFP generator does not support all styles of XSL FO borders (see above limitation on lines). All other borders are drawn as
solidlines. -
AFP generator does not support some of XEPOUT elments.
-
AFP generator does not support colors other than RGB, Greyscale, CMYK, and Spot (Highlight).
-
Shading option is not supported for Highight color. More details in Highlight Color Support.
-
Image clipping works only for images having the same (or higher) resolution as AFP document.
-
Shading patterns work for rectangular areas only.
-
Shading patterns are limited for only those areas filled with grayscale color.
-
Bilevel images (including shading patterns) are mixed with their background. Their white points appear transparent.
-
AFP backend cannot process strip TIFF images with absent 'RowsPerStrip' tag. 'RowsPerStrip' tag may be absent in TIFF image, although this is not recommended by TIFF Specification (Revision 6.0). This is a limitation of used library, AWT.
-
Custom stylesheets implementing Barcodes MUST produce Barcode alone item within SVG block if barcodes are generated with BC:OCA. For example:
<svg> <!-- nothing before desc -> <desc /> <svg:line /> <!-- only lines displaying barcodes --> … <svg:line /> <!-- nothing after barcodes’ lines --> </svg>
-
Ligatures are not supported yet; they are displayed as question marks ("?"). In order to avoid this, ligatures must be disabled for each font used.
-
Code3of9 barcode does not correctly produce characters: dollar sign ($), slash (/), plus (+), and percent (%).
-
Code128 and 4state-AU barcodes may display wrongly in some cases.
-
SVG text support only the following rotation values (in degrees): 0, 90, 180, 270.
-
SVG text enclosed into viewbox may be distorted if zoom factors by X and Y axis are different; In this case, root-mean-square value is used.
-
International Character Set support: Currently, each Character Set has single CodePage and AFP CodePage assigned, and this cannot be configured. More details in International Character Set Support section.
-
Unicode character used for text bullets must belong to any of supported Character Sets. The most common Unicode characters
0x2022and0x2023belonging to General Punctuation Character Set are not supported. -
Currently, XEP does not support outline AFP fonts.
-
Embedding, subsetting and algorithmic slanting of native AFP fonts are not supported.
-
Q: Upon every file I'm trying to process with XEP, the following error is displayed:
"UnsupportedEncodingException: Cp037"
A: By default, JRE is installed without charsets.jar file. This file is required for XEP. Please run JRE installer and check "additional languages support" checkbox.
Note:
Actual checkbox name may vary for different versions of JRE.
This section contains the following topics:
SVG documents can be generated through the following:
-
XEP Assistant - When formatting the XML file using the XEP Assistant, select SVG as the format, as described in XEP Assistant.
-
Command Line - Using the command line, SVG documents can be generated.
-
To generate an SVG document, use the parameter -svg:
-svg <svg document file name>
For more information, please refer to Using the Command Line.
-
SVG generator supports PNG, JPEG and SVG format files.
Notes on SVG support in SVG generator:
-
For an SVG image to be processed, it must have an intrinsic size. If
heightorwidthare expressed in percents, aviewBoxattribute must be present. -
SVG image
Heightandwidthcan be expressed in px, pt, cm, mm and in units. Other unit identifiers are not supported.
Configuration of the SVG generator is performed in a usual way all XEP generators are configured. All configuration options for SVG generator are child elements of XEP configuration file element <generator-options format="SVG">. Each SVG generator configuration option is an element option and looks like
<option name="OPTION_NAME" value="OPTION_VALUE"/>.
The two options - EMBED_IMAGES and DPI (resolution of an SVG viewer) - can be passed to SVG generator.
Note:
SVG parameters can be set in three different ways, depending on your specific needs:
-
Configuration file - in this case, the parameter value applies to all documents processed with this configuration file.
-
Environment variable (Generator option) - passed within command line and applies for current run of XEP. Generator option value overrides Configuration file values.
-
Processing Instruction - passed within Processing Instruction (PI) inside XSL:FO document. Please refer Output Format Settings section for more details on processing instructions. Processing Instruction value overrides Generator option and Configuration file values.
SVG generator's prefix for Generator options is H4SVG. So, EMBED_IMAGES parameter will look like this:
-DH4SVG.EMBED_IMAGES=true
SVG generator's prefix for Processing instructions is xep-svg-. So, EMBED_IMAGES parameter will look like this:
<?xep-svg-embed-images true?>
Processing Instruction may appear at document level or page level.
-
SVG generator does not support lines with styles other than
solid,dashed, anddotted; all other lines looksolidin generated SVG documents. -
SVG generator does not support all styles of XSL FO borders (see above limitation on lines). All other borders are drawn as
solidlines. -
SVG generator does not support
internal-bookmarkandexternal-bookmarkXEPOUT elments. -
SVG generator does not support font embedding and subsetting.
This section contains the following topics:
This appendix describes the implementation of XSL Formatting Objects in XEP — an XSL Engine for PDF developed by RenderX, Inc, version 4.14. 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.
| § | 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[a] |
| 6.6.7 | <fo:inline> |
Yes |
| 6.6.8 | <fo:inline-container> |
No[b] |
| 6.6.9 | <fo:leader> |
Yes[c] |
| 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[d] |
| 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[e] |
| 6.11.4 | <fo:retrieve-marker> |
Yes |
|
[a] [b] All content is placed inline. [c] In this version, only plain text can be put inside
leaders with | ||