RenderX

Chapter 6 of the IREn User Guide

IREn AFP Generator

6.1. Generating AFP Documents

AFP documents can be generated through the following:

  • IREn Assistant - When formatting the XML file using the IREn Assistant, select AFP as the format, as described in Chapter 3.

  • 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 Chapter 4.

    • 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 Section 6.8.

6.2. Fonts

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.

6.2.1. Font Mapping

IREn 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 Section D.1.4. 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 IREn to obtain font metrics. In this case, the metrics of TrueType/OpenType fonts are used for formatting; after that, when generating AFPDS stream, IREn uses mapped font values to refer in result document.

Therefore, AFP generator for IREn supports all kinds of fonts supported by IREn.

Mapping FO fonts and native AFP fonts can be configured in the IREn configuration file, in the AFP generator configuration section. Please refer to Section 5.1.4 for details.

6.3. Images

6.3.1. Image Support

Raster image handling in AFP generator for IREn is based on target printer's capability of supported image formats. If certain image format is supported by target AFP printer, the AFP generator for IREn puts the unchanged image into the AFP data stream. Otherwise, it reads entire image raster and compresses it into one of known native image formats.

ImageCompression ­AlgorithmProperties
Bi-level images0x82G4 MMR—Modified, 1 bit per pixel, RLE-compressed
Grayscale images0x038 bits per pixel, uncompressed

Note: Modern AFP printers support advanced raster image formats such as JPEG. It is highly recommended to use native images if your printer supports it because IREn does not need to decompress entire raster. This provides with fewer memory consumption, gives significant performance boost (up to 10 times), and allows for producing smaller output files.

By default, no native image formats are allowed.

To find out whether your printer supports certain data formats, refer your printer's manual.

The following formats are used for raster compression:

You may refer Section 6.8.5 section to find how to configure native image formats.

Note: In AFP, bi-level images are mixed with their background. Therefore, white points appear transparent.

6.3.2. Referencing Images

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.

In order to set the image to be included in a separate resource file, the resource file name should be specified as a RESOURCE formatting option and also the image should be given an unique Object Token (via the AFPObjectToken pinpoint instruction). If an Object Token is not set, the image is not included for relocation to the resource file. If an Object Token is not unique, all subsequent images with the same Object Token are ignored.

For example:

<rx:pinpoint value="AFPObjectToken=CAT00001,embed"/>
<fo:external-graphic src="url(cat.jpg)" />

Alternatively, the ALL_IMAGES_TO_RESOURCE configuration option forces all images to be placed in the resource file, assigning them with automatic Object Tokens.

Further configuration options are described in Section 6.8.6.

Note: Pinpoints are an experimental feature and may be changed at next release. Please contact RenderX support before use for other purposes.

6.3.3. Image Clipping

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.

6.4. Highlight Color Support

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

6.5. Graphics Support

Scalable Vector Graphics (SVG) is a language for describing two-dimensional vector graphics in XML.

AFP Backend 4.31.529 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, IREn 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.

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

6.6. Barcodes Support

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:

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.

Starting from version 4.29, IREn contains its own extension <rx:barcode> to XSL-FO for Barcode support. Please refer Section B.24 for more details about its implementation.

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 Section 6.5 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:

www.renderx.com/tools/word2fo.html

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 Section 6.11 for more details about AFP Backend limitations.

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.

6.7. FORMDEF Resource

6.7.1. What is a FORMDEF Resource?

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 IREn AFP Generator has limited support for generation of FORMDEF resources. In general, complex features like overlays and page segments are not supported.

6.7.2. Generating a Document with FORMDEF Resource

FORMDEF is a MO:DCA resource. Therefore, two steps are required in order to generate a document with FORMDEF.

  1. You must specify the resource file on the IREn command line.

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

6.7.3. FORMDEF Processing Instructions

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 IREn 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 IREn processes only the first occurrence of this instruction, as instruction ids are same.

FORMDEF Syntax

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.

Other FORMDEF Instructions

Other FORMDEF instructions include:

  • xep-afp-invoke-medium-map - puts IMM (Invoke Medium Map) instruction before page's BPG.

    This instruction is used in order to invoke Medium Maps that are already uploaded into target printer environment. If two sequential pages invoke the same Medium Map, only the first page's BPG will be preceded with corresponding IMM. To override this behaviour and make IREn put IMM before each BPG, regardless of this check, use force attribute.

    If name exceeds 8 characters, AFP backend trims it to this length and automatically adds 0x02 (Fully Qualified Name) triplet.

    Note: IREn is unable to ensure validity of Medium Maps uploaded into the printer so it does not check if map-name is valid.

    Format:

    <?xep-afp-invoke-medium-map name="map-name" [force="true"]?>

    Attributes:

    • name - name of the map to be invoked.

    • force - whether to force IMM instruction on each page applied.

    Note: xep-afp-invoke-medium-map is put into the main output stream only and thus it does not require resource file specified.

6.8. Configuring the IREn AFP Generator

Configuration of the AFP generator is performed in a usual way all IREn generators are configured.

Note: Rendering to AFP requires that some "pretty-print" features were disabled in the core of IREn. Starting from version 4.19, AFP generator users are encouraged to set the following IREn core options:

<option name="MERGE_WHITE_SPACE" value="false"/>
<option name="LTF" value="1000"/>

This is especially true if the local fonts IREn uses for formatting have somewhat different metrics for certain glyphs than the fonts residing on AFP device. The MERGE_WHITE_SPACE would prohibit IREn from introducing variable inline progression for white space character, while LTF (Line Thickness Factor) controls handling minor overflows. Whenever the content exceeds its container by less than (1/LTF), it will get "squeezed" by manually displacing glyphs, avioding unnecessary line wraps and long holes on preceding lines. However, with AFP such processing often produces unnecessary side effects, so it is recommended to disable this feature. The default is 20, which makes 1/20th (5%) of line width gets squeezed. Setting it to 1000 makes it 1/1000th, which is virtually zero.

All other configuration options for AFP generator are child elements of IREn 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 IREn. 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.

6.8.1. Configuring Character Sets

AFP generator for IREn 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 IREn 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 <code-range> element. It has the following attributes:

  • from and to defining beginning and ending values of Unicode characters belonging to the character range; Must be hexadecimal value; Required;

Codepages are defined by <codepage> element. It has the following attributes:

  • name string value defining Java standard name of Codepage; In Java environment, there must be a registered charset provider with the given name; Required;

  • ibm-name string value defining AFP codepage specification ("Txxxxxxx"); Required;

  • forcelatin a boolean (true or false) value defining whether the codepage contain Base Latin characters in lower half of code bytes (0x00..0x7F); Optional; Default=true;

  • desc providing text description of the code page; Optional;

Specially mapped characters are defined by <character> element. It has the following attributes:

  • unicode defining two-byte hexadecimal value of specially mapped character; Required;

  • afp defining one-byte hexadecimal value of mapped character within target Codepage; Required;

  • desc providing 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 Section 6.10 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.

6.8.2. Configuring Fonts

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

    1. AFP substitution font for font-weight="normal" font-style="normal"

    2. AFP substitution font for font-weight="normal" font-style="italic"

    3. AFP substitution font for font-weight="bold" font-style="normal"

    4. AFP substitution font for font-weight="bold" font-style="italic"

    5. AFP substitution font for symbolic subset and font-weight="normal" font-style="normal"

    6. AFP substitution font for symbolic subset and font-weight="normal" font-style="italic"

    7. AFP substitution font for symbolic subset and font-weight="bold" font-style="normal"

    8. AFP substitution font for symbolic subset and font-weight="bold" font-style="italic"

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

6.8.3. Configuring Highlight Color Table

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

6.8.4. Configuring Shading Patterns

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

    • 1 or true or yes - Shading patterns will be used

    • 0 or false or no - 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.

    • 1 or true or yes - "replicate-and-trim" is used

    • 0 or false or no - "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 off for 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 0 and no greater than 1

    Example:

    <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 of 0.25 (1/4) will produce raster image 16 times smaller.

    This option applies only if USE_SHADING_PATTERNS equals to true and USE_REPLICATE_AND_TRIM equals to false.

  • TRY_USING_TIFF_COMPRESSION option allows the user to specify whether AFP backend attempts to compress shading patterns raster images with TIFF encoding.

    • 1 or true or yes - AFP Backend attempts to compress shading pattern rasters (default)

    • 0 or false or no - AFP Backend does not attempt to compress shading pattern rasters

    Example:

    <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 true and USE_REPLICATE_AND_TRIM equals to false.

6.8.5. Configuring Data Types

IREn allows configuring which Native data types will be put to AFP data stream without recompressing the raster.

The element <data-types> is a container for Native data types configuration. Its attribute default-name defines which algorithm will be used for thos formats that are not configured as native.

Each Data type is configured within <data-type> element. It has the following attributes:

  • name - verbose name of data type. The attribute name contains any string value and must be unique.

  • allow-instream - whether the data type is allowed in AFP data stream.

    • 1 or true or yes - Data type is allowed (default)
    • 0 or false or no - Data type is not allowed

  • compression-code defining one-byte numeric value of AFP compression code; may be decimal or hexadecimal; Required;

  • recording-code defining one-byte numeric value of AFP recording code; may be decimal or hexadecimal; Required;

Data type definition contains the following child elements:

  • List of MIME-types associated with the Data type, represented <mime-type> element;

Each MIME-type is configured within <mime-type> element. It has the following attributes:

  • code - verbose code of MIME-type. The attribute code contains any string value and must be unique across all <data-type> elements.

The following example demonstrates how to configure necessary Data types for AFP generator:

<data-types default-name="G4 MMR">
  <data-type name="Uncompressed" allow-instream="true"
    compression-code="0x03" recording-code="0x01">
  </data-type>
  <data-type name="G4 MMR" allow-instream="true"
    compression-code="0x82" recording-code="0x01">
  </data-type>
  <data-type name="JPEG" allow-instream="true"
    compression-code="0x83" recording-code="0x01">
    <mime-type code="image/jpeg" />
    <mime-type code="jpeg" />
  </data-type>
</data-types>

See Image Encoding section of I:OCA Reference (Chapter 5, page 35) for list of compatible AFP image formats.

See Section 6.3.1 section for more information about native image formats.

6.8.6. Other Configuration Options

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

    • 2 - AFP generator prints warnings and information messages

    Example:

    <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, never appended.

  • 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 is obsolete. Use default-name attribute of <data-types> element to define default compression algorithm.

  • USE_PTOCA_LEVEL defines maximal level of PT:OCA commands subset.

    • 1 - Use PT1 only (default)

    • 2 - Use PT1 and PT2 only

    • 3 - Use PT1, PT2, and PT3 subsets

    Example:

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

    • 3 - Use Levels 1 and 3

    Example:

    <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 Section 6.5 for more details on G:OCA implementation in IREn 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 only

    Example:

    <option name="USE_BCOCA_LEVEL" value="1"/>

    Set this parameter to 1 in order to enable generating BC:OCA data within output stream.

    Please refer Section 6.6 for more details on supported barcode types and barcodes implementation notes in IREn AFP Generator.

6.9. Bullets support

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>&#x00b0;</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 0x2022 and 0x2023 used 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 Section 6.11 for more details.

6.10. International Character Set Support

AFP Generator for IREn 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 IREn 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:

NameAFP CodePageText CodePageUnicode Characters RangeComment
Basic LatinT1V10500Cp5000x0000-0x007FBasic Latin is automatically included into all character sets
Latin-1T1000819Cp8190x0080-0x00FFContains umlaut characters for Western-European languages
HebrewT1000424Cp4240x0590-0x05FFContains characters for Hebrew
Greek/CopticT1000875Cp8750x0370-0x03FFContains characters for Greek language
CyrillicT1000866Cp8660x0400-0x04FFContains characters for Cyrillic languages
ChineseT1094700Cp9500x4E00-0x9FFFContains characters for Chinese language (simplified)

Please refer Section 6.8.1 for more details.

6.11. Limitations of the IREn AFP Generator

  • AFP generator uses precision of 1/20 of point so its precision is 50 times worse than in other IREn backends.

  • AFP generator has limited support of SVG images. For more information about G:OCA implementation please refer Section 6.5.

  • AFP generator does not support lines with styles other than solid, dashed, and dotted; all other lines look solid in generated AFP documents.

  • AFP generator does not support SVG/G:OCA lines with style other than solid; all lines look solid in 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 solid lines.

  • 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 0x2022 and 0x2023 belonging to General Punctuation Character Set are not supported.

  • Currently, IREn does not support outline AFP fonts.

  • Embedding, subsetting and algorithmic slanting of native AFP fonts are not supported.

6.12. Frequently Asked Questions

  • Q: Upon every file I'm trying to process with IREn, the following error is displayed:

    "UnsupportedEncodingException: Cp037"

    A: By default, JRE is installed without charsets.jar file. This file is required for IREn. Please run JRE installer and check "additional languages support" checkbox.

    Note: Actual checkbox name may vary for different versions of JRE.

  • Q: After upgrading to IREn 4.19, text in AFP seems garbled; white spaces appear in the middle of words. What's wrong?

    A: Briefly, you have to set MERGE_WHITE_SPACE option to the value of false. See Section 6.8

    IREn Formatter employs "White Space Tracking" feature in order to produce better printing results.

    Effectively, the Formatter splits text into chunks (inside or between the words which stands for Character, Word, and Sentence tracking) and set arbitrary alignment for each chunk individually.

    This is quite effective for those formats that are displayed on screen or printed, using exactly the same fonts as those been used for formatting.

    It does not work with AFP fonts, however. The fonts used for formatting are TrueType or OpenType, while those residing in AFP printer memory have slightly different metrics.

    In case of AFP Viewers, such a problem is also a case due to rounding errors.

    IREn 4.18 and earlier purposefully disabled White Space Tracking if they noticed AFP key in the license. This helped AFP printing, but did not work for the customers who print both to AFP and other formats. Starting from version 4.19, White Space Tracking option is independent on the licenses used.

Download the complete IREn User Guide as PDF