XEP 4.2 Reference for Java

The behaviour of XEP formatter is controlled by a single configuration file, that must always be made accessible to the formatter. It stores information about core formatter options, lists fonts available to the formatter, and describes language-specific data. Having a single file that completely defines XEP's behaviour permits easy switching between different XEP configurations, and facilitates environment tuneup.

Methods to locate the configuration file are different on different platforms; please refer to specific platform documentation for details. By default, the formatter looks for file named xep.xml in the current directory of the process where it runs.

The configuration file is an XML document in a special namespace: "http://www.renderx.com/XEP/config". Its formal grammar (DTD) is given in Appendix B. The root of configuration file should be a <config> element. It includes three major subsections:

Through the rest of this chapter, we discuss the overall structure of each section in the configuration file. Specific instructions for setting up fonts and output generators are contained in the respective chapters of this Reference.

Some parameters can accept URLs as values. In these cases, the location of 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 the effect of xml:base attribute.

Usually, a monolithic configuration file is the most convenient way to store XEP configuration. However, you may need to move parts of configuration into separate files; for example, when font configuration needs to be 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 a href attribute.

XEP core and backend options can also be specified in platform-dependent ways, overriding values set in the configuration file. Please refer to the documentation provided with your version of XEP for details.

The operation of XEP 4.2 is controlled by a number of options. An option has a name and an associated value: name=value. In the configuration file, an option is defined by an <option> element; its name attribute defines option's name, and the value sets its value. XEP core options are always specified as a direct children of the <options> element. The following core options are defined for XEP 4.2:

Principal output formats for XEP are Adobe Portable Document Format (version 1.3 or higher), or PostScript (Level 2 or 3). Each format is produced by a special module, called output generator (sometimes referred to as backends). Apart from the two standard generators, there is also a special backend that prints out an XML document corresponding to the stream of drawing events issued by the formatter core. This intermediate XML format is typically used for postprocessing manipulation or debugging through XEP API; it is described in Appendix C.

Each generator has configuration parameters that you can modify to control different aspects of produced documents. PDF generator parameters control PDF security options, PDF stream compression, viewer preferences etc. PostScript generator parameters control PostScript language options and Distiller parameters (via pdfmark operators). The only parameter of the XML output generator controls representation of images in the resulting document. All these parameters are thoroughly discussed in the chapter Output Formats.

Default settings for output generators can also be specified inside <options> element in the configuration file. To distinguish them from core options, they are wrapped in <generator-options> element. Attribute format of this element defines target output format for the generator. For example, the following fragment turns on linearization for PDF generator and sets initial zoom factor to fit-width for 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>
          

Configurable parameters for all generators are listed in Appendix A, and discussed in more details in chapter Output Formats.

Font configuration is specified inside <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.

<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>

Language-specific configuration parameters are stored in the third major section of the configuration file, inside a <languages> element. It contains one or more <language> elements; each <language> stores information pertaining to a single language. The language is identified by two attributes: name attribute provides a name of the language, and codes attribute contains a list of codes used to refer to the language in the XSL-FO input data. Codes in the list are separated by spaces.

In XEP 4.2 two kinds of data are configurable in this section of the configuration files: hyphenation patterns and language-specific font aliases.

Legend:

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

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

Support for expressions is subject to the following limitations:

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

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

<?xep-pdf-unicode-annotations value?>
<?xep-postscript-unicode-annotations value?>

These processing instructions enable or disable use of Unicode to represent PDF annotation strings (bookmark text, document info, etc). In PostScript, the information is coded in pdfmark operators, and used for further conversion to PDF. Permitted values are:

The instruction should be placed at the top of the document, before <fo:root> element.

This feature can also be controlled by UNICODE_ANNOTATIONS option in the configuration file for PDF and PostScript generators.

<?xep-pdf-initial-zoom value?>
<?xep-postscript-initial-zoom value?>

These processing instructions specify magnification factor when the PDF document is first opened in a PDF viewer. In PostScript, the information is coded in pdfmark operators, and used for further conversion to PDF. Permitted values are:

The instruction should be placed at the top of the document, before <fo:root> element.

This feature can also be controlled by INITIAL_ZOOM option in the configuration file for PDF and PostScript generators.

<?xep-pdf-view-mode value?>
<?xep-postscript-view-mode value?>

These processing instructions specify the viewer mode to open the PDF document. In PostScript, the information is coded in pdfmark operators, and used for further conversion to PDF. Permitted values are:

The instruction should be placed at the top of the document, before <fo:root> element.

This feature can also be controlled by VIEW_MODE option in the configuration file for PDF and PostScript generators.

<?xep-pdf-drop-unused-destinations value?>
<?xep-postscript-drop-unused-destinations value?>

These processing instructions specify whether named destinations are created for objects not referenced within the document. In PostScript, the information about named destination is coded in pdfmark operators, and used for further conversion to PDF. Permitted values are:

The instruction should be placed at the top of the document, before <fo:root> element.

This feature can also be controlled by 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 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(………).

The instruction should be placed at the top of the document, before <fo:root> element.

<?xep-pdf-pdf-x value?>

This processing instruction sets PDF/X compliance level. Permitted values are:

The instruction should be placed at the top of the document, before <fo:root> element.

These processing instructions define features that support prepress production workflow.

<?xep-pdf-crop-offset value?>
<?xep-postscript-crop-offset value?>

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 correspondent edges of the /MediaBox. Rules for expanding the value are the same as for the padding property in XSL FO.

<?xep-pdf-bleed value?>
<?xep-postscript-bleed value?>

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 correspondent 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-width value?>
<?xep-postscript-crop-mark-width value?>

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-width value?>
<?xep-postscript-bleed-mark-width value?>

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-mark URL?>
<?xep-postscript-printer-mark URL?>

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(………).

To set prepress options for all pages in a document, the respective instruction should appear at the top of the document, before <fo:root> element. To control prepress settings for a single page, the instructions should be specified inside the <fo:simple-page-master> object used to generate that page.

<?xep-pdf-pdf-version value?>

This processing instruction sets target PDF version. Permitted values are 1.3, 1.4, and 1.5. The default value is 1.4. When set to 1.3, advanced features of PDF 1.4 are disabled: in SVG images, fill-opacity and stroke-opacity properties will be ignored.

The instruction should be placed at the top of the document, before <fo:root> element.

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. Permitted values are:

The instruction should be placed at the top of the document, before <fo:root> element.

This feature can also be controlled by 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. Permitted values are:

The instruction should be placed at the top of the document, before <fo:root> element.

This feature can also be controlled by LINEARIZE option in the configuration file for the PDF generator.

A group of processing instructions controls PDF security settings.

<?xep-pdf-ownerpassword value?>

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 permissions.

<?xep-pdf-userpassword value?>

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 will be authorized.

<?xep-pdf-userprivileges value?>

Sets the default privilege list for users accessing the resulting document with user password. The value must be a sequence composed of the following tokens:

Tokens can be specified in any order, separated by commas and/or spaces.

If neither user password nor owner password is set, security is disabled: the resulting PDF is not encrypted.

If the user password is not empty 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 not empty and the user password is not set, the resulting 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.

By default, neither of the passwords is set (security disabled). Default privilege list is annotate.

These instructions should be placed at the top of the document, before <fo:root> element.

These features can also be controlled by USERPASSWORD, OWNERPASSWORD, and USERPRIVILEGES options in the configuration file for the PDF generator.

<?xep-postscript-language-level value?>

This processing instruction sets target PostScript language level. Permitted values are 2 and 3. The default value is 3.. When language level is set to 2, some advanced features and font flavors are not available.

The instruction should be placed at the top of the document, before <fo:root> element.

This feature can also be controlled by 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 simply by pasting their contents at each occurrence. Permitted values are:

The instruction should be placed at the top of the document, before <fo:root> element.

This feature can also be controlled by CLONE_EPS option in the configuration file for the PostScript generator.

<?xep-postscript-page-device entryname entryvalue?>

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.

To set page device options for the whole document, the respective instructions should appear at the top of the document, before <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-out-embed-images value?>

This parameter controls if XML output generator should embed external image referenced in the document in the resulting document instance as Base64 strings. Values have the following meaning:

The instruction should be placed at the top of the document, before <fo:root> element.

This feature can also be controlled by EMBED_IMAGES option in the configuration file for the XML output generator.

XEP 4.2 supports the following raster graphics formats: PNG, JPEG, GIF, and TIFF.

When a bitmap graphic has no built-in resolution or dimension data. its resolution defaults to 120 dpi (5 dots of a 600-dpi printer) as prescribed by the CSS2 Spec. This is always the case for GIF images, but may also occur in other image types. The XSL Recommendation suggests, though not mandates, using 0.28 mm as a pixel size in such cases; this corresponds to 90 dpi resolution. In our opinion, a smaller pixel size gives better print results: the proportion between pixel size and page width is similar to that of a computer screen. With lower resolutions, it often happens that large GIF/JPEG images fit onto a screen but not into the printable area on the page. For interoperability with other XSL FO implementations, it is advisable to specify image size explicitly in XSL-FO code.

XEP 4.2 supports the following vector graphics formats: SVG, PDF (PDF generator only), EPS (PostScript generator only).

To use a Type 1 font with XEP, it is necessary to obtain an AFM file (Adobe Font Metrics) for the font, and specify the URL to it in the afm attribute of the <font-data> element. If the font is embedded into the resulting PDF or PostScript documents, a font outline file in PFA or PFB format is also needed; its location is specified in the respective attribute of the <font-data> — either pfa or pfb.

Example: suppose we have a metrics file foobar.afm and an outline file foobar.pfb. Its descriptor in the configuration file should look like this:

<font embed="true" subset="true">
    <font-data afm="foobar.afm" pfb="foobar.pfb"/>
</font>

If your Type 1 font uses non-standard glyph names, you may need an additional step — custom glyph list registration. This is discussed in more detail in the next section.

# Sample Glyph List

0020;space
0021;exclam;EXCLAMATION MARK
…
…
…

<font-data afm="foobar.afm"
           pfa="foobar.pfa"
           glyph-list="foo.glyphs"/>

TrueType fonts are supported in XEP 4.2, with the following limitations:

XEP supports both standalone TrueType fonts (normally stored in files with a *.ttf extension) and fonts in TrueType Collection files (they normally have a *.ttc extension). To use a standalone TrueType font with XEP, a URL to its font file should be specified in a ttf attribute to the <font-data> element, like in the example below:

<font-data ttf="FOOBAR.TTF"/>

To access a font from a TrueType Collection file, a URL to its font file should be specified in a ttc attribute to the <font-data> element. Additionally, it is necessary to specify the subfont number in a subfont attribute, like in the example below:

<font-family name="Gungsuh" embed="true">
    <font><font-data ttc="batang.ttc" subfont="3"/></font>
</font-family>

OpenType/CFF fonts fall into two groups, depending on whether the CFF font inside them is CID-based. Their level of support in XEP 4.2 is different.

To use an OpenType font with XEP, a URL to its font file should be specified in a otf attribute to the <font-data> element, like in the example below:

<font-data otf="KozMinPro-Regular-Acro.otf"/>

XEP uses the following line breaking algorithm:

The algorithm will be refined in further versions of XEP when more feedback about non-European scripting systems is received.

XEP 4.2 uses Unicode soft hyphen characters (U+00AD) to mark possible hyphenation points. These characters can be contained in the source XSL FO document (e.g. come from an external hyphenation software). XEP can also add them inside: it contains a hyphenator class that inserts soft hyphens to all text data before they are passed to the formatter.

The hyphenator implements Liang's algorithm (the same as used in TeX), and uses TeX format for hyphenation patterns. It recognizes sections patterns (for hyphenation patterns) and hyphenation (for exceptions); any other section in the pattern file is ignored. TeX macro definitions are not supported. Hexadecimal escape codes (e.g. ^^ae) and control characters (^^A) are supported; they can be used to encode non-ANSI European characters. Additionally, XEP recognizes a set of \rm macros for accented characters: \^a is â (a with circumflex accent), \l is ł (Polish barred l), etc.

XEP's distribution includes patterns for the following languages: English (American and British), French, German, Spanish, and Russian. All patterns were borrowed from CTAN (the Comprehensive TeX Archive Network, http://www.ctan.org/), with some modifications for non-English patterns. More patterns can be added if necessary; the procedure is described above, in the chapter on Configuring Hyphenation.

XEP supports right-to-left writing and mixed left-to-right/right-to-left text. Glyphs are placed on a line respecting the directionality and nesting of text spans, and glyph mirroring is performed for characters that change their orientation in right-to-left writing.

Java edition of XEP requires a Java VM 1.1.8 or higher to run properly. Sun JRE version 1.3 or later is highly recommended. It will also run under Microsoft Java VM version 5.00 or later.

The package contains the following files:

XEP 4.2 includes a GUI shell to configure XEP and run formatting. It is invoked as follows:

java com.renderx.xepx.x4u.as.Assistant

For the tool to run, a Java system property com.renderx.xep.CONFIG must be set, and point to a valid XEP configuration file. When XEP is installed, the setup creates a launch script that wraps the respective Java call, setting classpath and environment properly: x4u.bat for Windows systems, x4u for Unix/Linux.

XEP can be used from the command line either as a formatter of XSL-FO files, or as an XSL-FO transformer (provided that a JAXP XSLT transformer factory is present in the classpath). It has the following synopsis:

java com.renderx.xep.XSLDriver -help

Displays a synopsys reminder and exits.

java com.renderx.xep.XSLDriver 
        {option}  {-quiet | -version | -valid | -hosted}
        ( [-xml] <infile> [-xsl <stylesheet>] {-param <name=value>}
          | -fo <infile> 
          | -xep <infile> )
        [[-out | -pdf | -ps | -at] <outfile>] 
        [-format <output format>]

An option is a pair name=value preceded by -D prefix. For a full list of valid XEP options, please refer to Configuration above. Each option can be also set through a Java system property. For option X, the respective property is com.renderx.xep.X.

To run XEP, it is necessary to specify the location of its configuration file. By default, the formatter looks for a file names xep.xml in the current directory of the process; you can override this default by setting a CONFIG option in the command-line parameters, or through a system variable com.renderx.xep.CONFIG. The location can be specified either as a file name in the local filesystem, or as an URL.

Other switches have the following meaning:

Input:

Output:

A single dash ("-") as an input file name denotes standard input. Similarly, a dash as an output file name denotes standard output. Omitting input file specification also means reading from standard input.

The default output format is PDF. If the output file name is not specified, it is constructed from the source file name by adding an extension corresponding to the selected format.

Program exit codes are zero for successful termination and non-zero for failure. If -hosted switch is specified, no exit code is ever returned; failures result in an exception being thrown.

If you haven't set CLASSPATH system variable, you will need to supply an additional -classpath parameter in your Java call, to include required library files into class search path. You may need to add an -Xmx switch to the Java call mentioned above in order to increase the amount of memory available to Java. Recommended value of -Xmx is about 80% of physical RAM available on the computer that runs XEP.

XEP installation includes a launch script that wraps a respective Java call: xep.bat for Windows systems, xep for Unix/Linux. This script is preconfigured during XEP installation.

There is also a command-line interface to the validator component of XEP that lets you check the structure of your XSL FO file without formatting them:

java com.renderx.xep.Validator arguments

Arguments are one or more XSL FO file names, validated one after another. There is a preconfigured launch script, too: validate.bat for Windows systems, validate for Unix/Linux.

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 Sun (provided that you have included resolver classes in the classpath, and properly configured it):

java 
   -Dcom.renderx.sax.entityresolver=com.sun.resolver.tools.CatalogResolver
   -Dcom.renderx.jaxp.uriresolver=com.sun.resolver.tools.CatalogResolver
   …

For further information about catalogs and entity resolution, we recommend reading an article by Norman Walsh: http://www.sun.com/xml/developers/resolver/article/.