|
Download Now!


 RenderX offers all our software on a trial basis so that our prospects can
easily see why thousands of customers have selected XEP to meet their needs.
Why not download a trial version today and
see for yourself!
|
 |
XEP User Guide: XSL FO Formatting
|
|
© Copyright 2005-2008 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
- 1. Preface
- 1.1. What's in this Document?
- 1.2. Prerequisites
- 1.3. Acronyms
- 1.4. Technical Support
- 2. Overview
- 2.1. Overview
- 2.2. Introduction
- 2.3. Basic Terms
- 3. XEP Assistant
- 3.1. What is XEP Assistant?
- 3.2. Opening XEP Assistant
- 3.3. Rendering an XML File using XEP
Assistant
- 3.3.1. Opening a File
- 3.3.2. Formatting a File
- 4. Using the Command Line
- 4.1. Running
XEP
- 4.2. XEP
Options
- 4.3. XEP
Switches
- 4.4. XEP
Arguments
- 4.5. Examples of Running XEP from the Command Line
- 5. Configuring XEP
- 5.1. Configuring XEP using XEP Assistant
- 5.1.1. Configuring Main Settings
- 5.1.2. Configuring Backends
- 5.1.2.1. Configuring the Backend for PDF Files
- 5.1.2.2. Configuring the Backend for PostScript Files
- 5.1.2.3. Configuring the Backend for AFP Files
- 5.1.2.3.1. AFP Fonts
- 5.1.3. Configuring Languages
- 5.1.4. Configuring Fonts
- 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 Viewer Preferences (PDF, PostScript)
- 5.2.3.4. Treatment of Unused Destinations (PDF, PostScript)
- 5.2.3.5. ICC Profile (PDF)
- 5.2.3.6. PDF/X Support (PDF)
- 5.2.3.7. PDF/A Support (PDF)
- 5.2.3.8. Prepress Support (PDF, PostScript)
- 5.2.3.9. PDF Version (PDF)
- 5.2.3.10. Compression of PDF Streams (PDF)
- 5.2.3.11. Linearization (PDF)
- 5.2.3.12. Document Security (PDF)
- 5.2.3.13. PostScript Language Level (PostScript)
- 5.2.3.14. EPS Graphics Treatment (PostScript)
- 5.2.3.15. Page Device Control (PostScript)
- 5.2.3.16. Images Treatment in XML Output (XML)
- 5.2.4. Configuring Fonts
- 5.2.4.1. Fonts and Font Families
- 5.2.4.1.1. Embedding and Subsetting Fonts
- 5.2.4.1.2. AFP Fonts
- 5.2.4.1.3. Algorithmic Slanting
- 5.2.4.1.4. Ligaturization
- 5.2.4.2. Font Groups
- 5.2.4.3. Font Aliases
- 5.2.5. Configuring Languages
- 5.2.5.1. Configuring Hyphenation
- 5.2.5.2. Language-Specific Font Aliases
- 6. XEP AFP
Generator
- 6.1. Generating AFP Documents
- 6.2. Fonts
- 6.2.1. Font Mapping
- 6.3. Images
- 6.3.1. Image Support
- 6.3.2. Referencing Images
- 6.3.3. Image Clipping
- 6.4. Highlight Color Support
- 6.5. Graphics Support
- 6.6. Barcodes Support
- 6.7. FORMDEF Resource
- 6.7.1. What is a FORMDEF Resource?
- 6.7.2. Generating a Document with FORMDEF Resource
- 6.7.3. FORMDEF Processing Instructions
- 6.7.3.1. FORMDEF
Syntax
- 6.8. Configuring the XEP AFP Generator
- 6.8.1. Configuring Character Sets
- 6.8.2. Configuring Fonts
- 6.8.3. Configuring Highlight
Color Table
- 6.8.4. Configuring Shading
Patterns
- 6.8.5. Other Configuration
Options
- 6.9. Bullets support
- 6.10. International
Character Set Support
- 6.11. Limitations of the XEP AFP Generator
- 6.12. Frequently
Asked Questions
- 7. Appendix A. XSL-FO Conformance
- 7.1. XSL-FO Support
- 7.1.1. Formatting
Objects Supported by XEP
- 7.1.2. Formatting Properties
Supported by XEP
- 7.1.3. Notes on
Formatting Objects Implementation
- 7.1.4. Supported
Expressions
- 7.1.5. Color
Specifiers
- 7.1.6. XSL 1.1
Support
- 7.1.6.1. Document Outline (Bookmarks)
- 7.1.6.2. Indexes
- 7.1.6.3. Last Page Number Reference
- 7.1.6.4. Change Bars
- 7.1.7. Extensions to the
XSL 1.0 Recommendation
- 7.1.7.1. Document Information
- 7.1.7.2. Document Outline (Bookmarks)
- 7.1.7.3. Indexes
- 7.1.7.3.1. Index Term Markup
- 7.1.7.3.2. Index Entries
- 7.1.7.4. Flow Sections
- 7.1.7.5. Last Page Number Reference
- 7.1.7.6. Change Bars
- 7.1.7.7. Background Image Scaling and Content Type
- 7.1.7.8. Initial Destination
- 7.1.7.9. Omitted Initial Header in Tables
- 7.1.7.10. Base URI Definition: xml:base
- 7.1.7.11. Border and Padding on Regions
- 7.1.7.12. Floats Alignment
- 7.1.7.13. Multicolumn Footnotes
- 7.1.7.14. Unique Footnotes
- 8. Appendix B. Linguistic Algorithms
- 8.1. Line-Breaking Algorithm
- 8.2. Hyphenation
- 8.2.1. Hyphenation Patterns
- 8.3. Support for Right-to-Left Writing Systems
- 8.3.1. Bidirectionality
- 8.3.2. Glyph
Shaping
- 9. Appendix C. Supported Fonts
- 9.1. Supported Fonts
- 9.1.1. PostScript
Type 1 Fonts
- 9.1.1.1. PostScript Fonts and Unicode
- 9.1.1.2. Standard Adobe
Fonts
- 9.1.2. TrueType
Fonts
- 9.1.3. OpenType/CFF Fonts
- 9.1.4. Supported AFP Fonts
- 10. Appendix D. Supported Graphic Formats
- 10.1. Supported Graphic
Formats
- 10.1.1. Bitmap Graphics
- 10.1.1.1. PNG
- 10.1.1.2. JPEG
- 10.1.1.3. GIF
- 10.1.1.4. TIFF
- 10.1.2. Vector Graphics
- 10.1.2.1. SVG
- 10.1.2.2. PDF
- 10.1.2.3. EPS
- 11. Appendix E. XEP Intermediate Output Format Specification
- 11.1. XEP
Intermediate Output Format Specification
- 12. Appendix F. Accessibility Support in XEP
- 12.1. Accessibility
Support in XEP
- 12.1.1. Tagged PDF
- 13. Appendix G. List of Output Generators' Options
- 13.1. List of Output
Generators' Options
- 14. Appendix H. Configuration File DTD
- 14.1. Configuration File DTD
- 15. Appendix I. Additional
Components
- 15.1. XEP Connector for jEdit
version 2.1
- 15.1.1. Changes since version 1.*
- 15.1.2. Overview
- 15.1.3. Terms of use
- 15.1.4. Installation
- 15.1.5. Copyright notices
- 15.2. XEP ANT Task 2.0 User's
Guide
- 15.2.1. Changes since version 1.*
- 15.2.2. Overview
- 15.2.3. Configuration
- 15.2.4. Parameters
- 15.2.5. Parameters specified as nested
elements
- 15.2.6. Examples
- 16. Index
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 runs on most systems where Java Virtual Machine 1.1.8 or newer is available. This includes:
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.12 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:
This section contains introductory information about XEP.
XEP is a library of Java classes that converts XML data to printable
formats, such as PDF, PostScript and AFP. 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 or AFP.
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.
-
Integration - XEP can be integrated into
other tools.
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.
- 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.
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.
Rendering an XML File using XEP Assistant
To render a file, first of all, you must open the XML or XSL-FO file you
wish to publish.
To open an existing XML or XSL-FO file:
-
From the main menu, click File.
The File menu is displayed.
-
From the File menu, click
Open.
A dialog box is displayed.
-
Browse to the file you wish to open.
The file is opened within XEP
Assistant.
Once an XML file is open, it must first be "transformed" before it
can be formatted to PDF, PostScript or AFP 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 or AFP).
To format an XML file:
-
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 and AFP.
|
| 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.
To add XSL parameters:
-
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.
To cancel formatting:
-
From the main menu, select
Formatting.
The Formatting menu is displayed.
-
Select Stop.
Formatting is canceled.
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.bat batch file.
-
On Linux, MAC, and UNIX, XEP can be run from a command shell,
via the xep bash 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
xep.xml file.
|
-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
xep.xmlfile is not
changed, and all subsequent file transformations are not
affected.
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
| Switch |
Description |
| -help |
Displays the detailed syntax of the XEP switches and
arguments.
|
| -hosted |
The Java Virtual Machine continues to run after the
renderer has completed rendering the file.
|
| -quiet |
By default, XEP writes detailed messages to the
command line console. These messages indicate the current status
and progress of the rendering process, as well as any warnings or
errors that may occur during the rendering
process.
Specify this switch to suppress the detailed
informational messages. In this case, the renderer outputs only
warning and error messages.
|
| -valid |
The validation is turned off; XEP does not validate the
input when rendering.
Note:
The rendering runs faster, but since the XML source is
not validated, there is a chance that the output will not be
correct.
|
| -version |
Displays detailed version information of the XEP rendering
engine.
|
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
| Argument |
Description |
| -xml |
The specified input file is an XML source document. When
the input file is an XML document, this argument may be
omitted.
|
| -fo |
The specified input file is an XSL-FO document ready to be
rendered.
|
| -xep |
The specified input file is an XEP file, generated
previously using the at output format. The XEP file is an XML
document that is an internal representation of the rendered
document.
|
| <infile> |
Specifies the input file. This argument is
required.
|
| -xsl <stylesheet> |
Specifies the XSL stylesheet XEP must use to transform the
input XML document into XSL-FO. <stylesheet> is the path
(absolute or relative to the working directory) of the XSL
stylesheet.
|
| -param <name=value> |
If the XSL stylesheet supports global parameters, they can
be set via the -param argument. Each XSL parameter you want to set
on the command line requires a separate -param argument.
|
| -<output format> |
Specifies the output format to render to. Available
output formats are: XEP, PDF, PostScript (PS), and
AFP.
-
at — Internal XEP format. This is an XML file that
represents the rendered document.
-
pdf — PDF format. This is the default output format if
no output format is specified.
-
afp — AFP format. AFP is an architecture standard for
High Volume Transaction Output supported by vendors of
printing equipment.
-
ps — PostScript format. PostScript is useful when
preparing a file to send to a printing service
provider.
-
xep — Internal XEP format (same as
at).
|
| -format |
Another way of specifying the output format. |
| -<outfile> |
Specifies the path and name of the output file. If no
output file is specified, the default output file is the same file
path and name as the input file with the
extension corresponding to file format.
|
Examples of Running XEP from the Command Line
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.12 build 20070123
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), 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.7 build 20060623
(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.xml
to PDF, using the stylesheet custom-fo.xsl to
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
|