XEP User Guide/XEP AFP Generator

From Docs

Jump to: navigation, search

Get PDF

Contents

Generating AFP Documents

AFP documents can be generated through the following:

  • XEP Assistant - When formatting the XML file using the File Assistant, select AFP as the format, as described in XEP Assistant.
  • 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 Using the Command Line.
    • 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 .
      Alternatively, you can use the configuration file variable. For more details, refer to Configuring the XEP AFP Generator .

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.

Font Mapping

XEP 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 Supported AFP Fonts. This variant requires a set of native AFP font files and allows using native AFP fonts metrics.
    You may also find useful information on AFP Fonts .
  • Another variant of configuration lets to map AFP native fonts to non-AFP fonts supported by XEP to obtain font metrics. In this case, the metrics of TrueType/OpenType fonts are used for formatting; after that, when generating AFPDS stream, XEP uses mapped font values to refer in result document.

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

Mapping FO fonts and native AFP fonts can be configured in the XEP configuration file, in the AFP generator configuration section. Please refer to Configuring Fonts for details.

Images

Image Support

Raster image formats are not supported by AFP, and color images are rarely supported by AFP printing systems. Therefore, depending on the configuration options, all raster images are either converted to bi-level images or grayscale images.

Image Properties
Bi-level images 1 bit per pixel, compressed
Grayscale images 8 bits per pixel, uncompressed


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

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.

The image can be included in the main AFP output file, or in a separate resource file as described in Other Configuration Options.

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.

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

Graphics Support

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

AFP Backend 4.13 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, XEP 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.
    XEP 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.

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:

http://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.

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 Graphics Support 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: http://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 Limitations of the XEP AFP Generator for more details.

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.

FORMDEF Resource

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

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

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

Configuring the XEP AFP Generator

Configuration of the AFP generator is performed in a usual way all XEP generators are configured. All configuration options for AFP generator are child elements of XEP 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 XEP. 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 .

Configuring Character Sets

AFP generator for XEP 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 XEP 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 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 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 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 International Character Set Support 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.

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.

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

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 .

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.
  • 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, if set to yes , turns on embedding of raster images as grayscale images, 8 bit per pixel, uncompressed.
    1 or true or yes - embed raster images as 8 bit
    0 or false or no - embed raster images in their original format (default)
    Example:
    <option name="AFPGrayImage" value="no"/>
  • 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 Graphics Support for more details on G:OCA implementation in XEP 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 Barcodes Support for more details on supported barcode types and barcodes implementation notes in XEP AFP Generator.

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>°</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 Limitations of the XEP AFP Generator for more details.

International Character Set Support

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

Name AFP CodePage Text CodePage Unicode Characters Range Comment
Basic Latin T1V10500 Cp500 0x0000-0x007F Basic Latin is automatically included into all character sets
Latin-1 T1000819 Cp819 0x0080-0x00FF Contains umlaut characters for Western-European languages
Hebrew T1000424 Cp424 0x0590-0x05FF Contains characters for Hebrew
Greek/Coptic T1000875 Cp875 0x0370-0x03FF Contains characters for Greek language
Cyrillic T1000866 Cp866 0x0400-0x04FF Contains characters for Cyrillic languages
Chinese T1094700 Cp950 0x4E00-0x9FFF Contains characters for Chinese language (simplified)

Please refer Configuring Character Sets for more details.

Limitations of the XEP AFP Generator

  • AFP generator uses precision of 1/20 of point so its precision is 50 times worse than in other XEP backends.
  • AFP generator has limited support of SVG images. For more information about G:OCA implementation please refer Graphics Support .
  • 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, XEP does not support outline AFP fonts.
  • Embedding, subsetting and algorithmic slanting of native AFP fonts are not supported.

Frequently Asked Questions

  • Q: Upon every file I'm trying to process with XEP, the following error is displayed:
    "UnsupportedEncodingException: Cp037"

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


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


Back to XEP User Guide

Personal tools