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: