<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
  <header>
    <title>Instructions for the Apache FOP extension</title>
    <authors>
      <person id="jmaerki" name="Jeremias Märki" email="jmaerki@users.sourceforge.net"/>
    </authors>
  </header>
  <body>
    <section>
      <title>Introduction</title>
      <p>
        This page describes how to generate barcodes within an XSL-FO document with that is
        processed with <fork href="ext:fop">Apache FOP</fork>.
      </p>
    </section>
    <section>
      <title>Setting up the barcode extension with Apache FOP 0.93 or later</title>
      <p>To setup the barcode extension, do the following:</p>
      <ul>
        <li>
          Add <code>barcode4j.jar</code> and <code>barcode4j-fop-ext.jar</code> to the
          <link href="../faq.html#classpath">classpath</link>.
        </li>
        <li>
          Alternatively, you can use the combined JAR:
          <code>barcode4j-fop-ext-complete.jar</code> which combines both
          <strong>Barcode4J</strong> and the FOP extension.
        </li>
      </ul>
    </section>
    <section>
      <title>Setting up the barcode extension with Apache FOP 0.20.5</title>
      <p>To setup the barcode extension, do the following:</p>
      <ul>
        <li>
          Add <code>barcode4j.jar</code> and <code>barcode4j-fop-ext-0.20.5.jar</code> to the
          <link href="../faq.html#classpath">classpath</link>.
        </li>
        <li>
         Alternatively, you can use the combined JAR:
          <code>barcode4j-fop-ext-0.20.5-complete.jar</code> which combines both
          <strong>Barcode4J</strong> and the FOP extension.
        </li>
        <li>
          <strong>Important:</strong> When you use FOP 0.20.5 together with
          <strong>Barcode4J</strong>, make sure you use the version of Avalon Framework that comes with
          <strong>Barcode4J</strong> (or the latest release of
          <fork href="ext:avalon">Avalon Framework</fork>). The version from FOP 0.20.5
          is slightly out-of-date.
        </li>
      </ul>
    </section>
    <section>
      <title>Using the barcode extension for Apache FOP</title>
      <p>This package contains an extension for <jump href="ext:fop">Apache FOP</jump> for
        generating barcodes.
      </p>
      <p>
        The barcode extension is tied to the follwing namespace:
        <strong><code>http://barcode4j.krysalis.org/ns</code></strong>
      </p>
      <p>
        To create a barcode the <link href="barcode-xml.html">Barcode XML</link> can be used within fo:instream-foreign-object elements.
      </p>
      <p>Here's an example (XSL-FO snippet):</p>
      <source><![CDATA[<fo:block>
  <fo:instream-foreign-object>
    <barcode:barcode
          xmlns:barcode="http://barcode4j.krysalis.org/ns"
          message="my message" orientation="90">
      <barcode:code128>
        <barcode:height>8mm</barcode:height>
      </barcode:code128>
    </barcode:barcode>
  </fo:instream-foreign-object>
</fo:block>]]></source>
      <p>
        The attribute "orientation" specifies the orientation of the barcode in degrees. The 
        attribute is optional and if set must be one of the following values:
        0, 90, -90, 180, -180, 270, -270.
      </p>
      <p>
        Some characters like RS (record separator) and GS (group separator) are sometimes required
        for certain applications but these characters are not valid XML characters and cannot be
        encoded. You can escape them by using Java's Unicode escaping syntax. To escape RS, you
        can write "\u001E". GS would be encoded as "\u001D" and so forth. If for some reason,
        you need to encode a string containing "\u" in your message, you will have to escape that
        using "\\u", i.e. the double backslash will be converted to a single backslash and the
        subsequent "u" is treated as a normal message character. It is an error to specify an
        incomplete escape sequence, i.e. "00\u012xsomething" will result in an error.
      </p>
    </section>
    <section>
      <title>Including FOP&#039;s <code>page-number</code> in Barcode Output</title>
      <p>
        FOP&#039;s page-number can be incorporated into barcode output.
        To incorporate the page-number into the barcode, insert
        <code>#page-number#</code> into your barcode message. For example,
        to insert a page number between <code>12345-</code> and <code>-6789</code>
        do the following:
      </p>
    <source>&#60;barcode:barcode
    xmlns:barcode="http://barcode4j.krysalis.org/ns"
    message="12345-#page-number#-6789"&#62;
  &#60;code39/&#62;
&#60;/barcode:barcode&#62;</source>
      <p>
        You can also use #page-number:{number-format}# where "{number-format}" is 
        the number format pattern supported by Java's 
        <fork href="http://java.sun.com/j2se/1.4.2/docs/api/java/text/DecimalFormat.html">java.text.DecimalFormat</fork>.
        This allows you to format page "<code>3</code>" as "<code>0003</code>" if you 
        need a constant number of characters in the barcode message. For this example,  
        you would use "#page-number:0000#" in the message.
      </p>
      <note>
        This feature is exclusively available in the FOP extension. It does not work
        in the XSLT extensions for Xalan-J or SAXON because only FOP has the 
        information about the current page number. The XSLT stage runs before any
        layout is processed.
      </note>
    </section>
    <section>
      <title>Using FOP from the command-line</title>
      <p>
        If you use FOP from the command-line (by calling fop.bat on Windows) it may not be
        enough to simply add the JAR files mentioned above to FOP's lib directory. On Unix
        all JAR files are automatically added to the classpath through the fop.sh script, so
        you only have to make sure that you don't have two different avalon-framework.jar
        files the the lib directory. On Windows, you will have to edit fop.bat and manually
        edit the entries there.
      </p>
    </section>
    <section>
      <title>Some technical background</title>
      <p>
        If you wonder how the FOP extension is found by FOP just by adding it to the classpath
        and by using the right namespace, open the extension JAR in a ZIP Viewer and look at
        the file in the directory META-INF\services\. FOP will look for this file at startup
        and will recognize the ElementMapping class.
      </p>
      <p>
        The normal FOP extension described above internally creates the barcode in SVG format.
        The generated SVG image is then converted by <fork href="ext:batik">Batik</fork> to the 
        target format (PDF, PostScript or whatever).
      </p>
      <p>
        The latest FOP versions even allow Barcode4J to generate the barcode in the native 
        output format.For example, when PostScript output is selected in FOP, Barcode4J creates 
        the barcode as an EPS graphic which is generally much faster than taking a detour via SVG.
      </p>
    </section>
  </body>
</document>
