![[logo]](Images/logo.gif){kind=logo}
Support Home
XEP User Guide
© 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
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 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.5. Configuring Languages
- 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. 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.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.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
- 9. Appendix C. Supported Fonts
- 10. Appendix D. Supported Graphic Formats
- 11. Appendix E. XEP Intermediate Output Format Specification
- 12. Appendix F. Accessibility Support in XEP
- 13. Appendix G. List of Output Generators' Options
- 14. Appendix H. Configuration File DTD
- 15. Appendix I. Additional Components
- 16. Index
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 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.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:
-
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 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.
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.
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 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).
-
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.
-
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.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.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:
- Configuring XEP using XEP Assistant
-
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.
Configuring Main SettingsConfiguring BackendsConfiguring LanguagesConfiguring Fonts
Configuring XEP via the XEP Configuration File
Configuration StructureCore OptionsConfiguring Output FormatsConfiguring FontsConfiguring LanguagesResolution of External Entities and URIs
This section describes how to configure XEP according to your preferences by using XEP Assistant.
To configure XEP:
The default configuration settings can be set in the Main tab.
Table 7. XEP Configuration Main Tab Parameters