<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.1//EN" "dtd/faq-v11.dtd">

<faqs title="Frequently Asked Questions">

  <part id="barcode4j">
    <title>Questions on Barcode4J in general</title>
    <faq id="license">
      <question>
        Under which license is Barcode4J published?
      </question>
      <answer>
        <p>
          It is published under the <fork href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, version 2.0</fork>.
          That means it is free and you can even use it in commercial software.
          However, we encourage you to read the Apache License to learn about all details.
        </p>
      </answer>
    </faq>
    <faq id="recognition">
      <question>
        Does Barcode4J support barcode recognition?
      </question>
      <answer>
        <p>
          No, Barcode4J is a barcode <strong>generator</strong> and does not support barcode recognition.
          If you're looking for a similarly licensed barcode recognition software written in Java,
          have a look at <fork href="http://code.google.com/p/zxing/">Zxing at Google Code</fork>.
        </p>
      </answer>
    </faq>
  </part>
  <part id="problems">
    <title>Problems</title>
    <faq id="printing-quality">
      <question>
        My barcode scanner can't read the barcode.
      </question>
      <answer>
        <p>
          There are many things that can go wrong when you generate and print
          barcodes. Please go to the
          <link href="troubleshooting.html#printing-quality">Troubleshooting page</link> for more
          information.
        </p>
      </answer>
    </faq>
    <faq id="wrong-characters">
      <question>
        My barcode scanner occasionally sends incorrect characters.
      </question>
      <answer>
        <p>
          Please consult the <link href="troubleshooting.html#wrong-characters">Troubleshooting page</link>
          for more information.
        </p>
      </answer>
    </faq>
  </part>
  <part id="docs">
    <title>Documentation</title>
    <faq id="forrest">
      <question>
        How can I help write documentation?
      </question>
      <answer>
        <p>
          This project uses <link href="ext:forrest">Apache Forrest</link> to
          generate documentation from XML. Please download a copy of Forrest,
          which can be used to <link
            href="ext:forrest/validation">validate</link>, <link
            href="ext:forrest/webapp">develop</link> and render a project site.
        </p>
      </answer>
    </faq>
  </part>
  <part id="fop">
    <title>Apache FOP</title>
    <faq id="fop-ext-failure">
      <question>
        The FOP extension fails.
      </question>
      <answer>
        <p>
          You will see error messages like this:
        </p>
        <source><![CDATA[
[ERROR] Unknown formatting object http://barcode4j.krysalis.org/ns^barcode
[ERROR] no handler defined for http://barcode4j.krysalis.org/ns:barcode foreign xml]]></source>
        <p>
          This usually indicates that the FOP extension is not present in the 
          classpath. Make sure you've got either both barcode4j.jar and 
          barcode4j-fop-ext-0.20.5.jar or the bigger 
          barcode4j-fop-ext-0.20.5-complete.jar in your classpath. If you work
          from the command-line you may have to change fop.bat or fop.sh.
        </p>
        <p>
          In rare circumstances this may be a result of a classloader problem.
          The resolution of problems like this depends on your environment.
        </p>
      </answer>
    </faq>
    <faq id="avalon-framework">
      <question>
        I've got error messages that contain the words "avalon" and "framework". What's wrong?
      </question>
      <answer>
        <p>
          Most probably you have an outdated version of
          <fork href="ext:avalon">Avalon Framework</fork> in your classpath. This can happen if
          you're working with FOP 0.20.5, for example, which contains an older version of
          Avalon Framework. Please use the one supplied with Barcode4J or download the
          latest release directly from the <fork href="ext:avalon">Avalon site</fork>.
        </p>
      </answer>
    </faq>
  </part>
  <part id="java">
    <title>Java</title>
    <faq id="classpath">
      <question>
        What's this "classpath" thing?
      </question>
      <answer>
        <p>
          The classpath is a set of locations where the Java Virtual Machine (JVM)
          can load Java code from. In the easiest case, the classpath is simply a
          directory, but normally the classpath consists of a list of filenames
          pointing to JAR files (essentially ZIP files with some special extensions).
          Barcode4J delivers several such JAR files. Let's see what the classpath
          looks like when you want to run Barcode4J from the command-line:
        </p>
        <source><![CDATA[
Windows:
java -cp lib\avalon-framework-4.2.0.jar;lib\commons-cli-1.0.jar;build\barcode4j.jar 
    org.krysalis.barcode4j.cli.Main

Unix:
java -cp lib\avalon-framework-4.2.0.jar:lib\commons-cli-1.0.jar:build\barcode4j.jar 
    org.krysalis.barcode4j.cli.Main]]>
        </source>
        <note>
          Instead of "-cp" you can also use "-classpath".
        </note>
        <p>
          The above works fine under JDK 1.4.x or higher. If you use JDK 1.3.x you
          need to add XML support (JAXP, Xerces and Xalan). JDK 1.4 has XML
          support built-in. You would add these libraries using the same pattern as
          shown above.
        </p>
      </answer>
    </faq>
    <faq id="endorsement">
      <question>
        How do I make sure the right XML parser and the right XSLT engine are used under JDK 1.4.x and higher?
      </question>
      <answer>
        <p>
          Starting with JDK 1.4, Java comes with XML support built-in. XML support comprises
          the JAXP API (SAX, DOM, parsing and XSLT processing APIs) plus implementations
          (Crimson/Xerces-J for basic XML support and Xalan-J as XSLT engine).
        </p>
        <p>
          By default, the implementations coming with the JDK are used even if you have
          different JAXP implementations in your classpath. There's a mechanism called
          "Endorsed Standards Override Mechanism" that allows you to override the default
          XML implementations with your own. See
          <fork href="http://xml.apache.org/xalan-j/faq.html#faq-N100CB">Xalan-J's FAQ entry</fork>
          or the
          <fork href="http://java.sun.com/j2se/1.4/docs/guide/standards/">documentation from Sun</fork>.
        </p>
      </answer>
    </faq>
    <faq id="headless">
      <question>
        What do I need to do to run Barcode4J on a "headless" server?
      </question>
      <answer>
        <p>
          Some output formats like EPS and SVG work on a headless server without any precautions,
          since they don't use any of the AWT infrastructure.
        </p>
        <p>
         However, if you use AWT or bitmap output Barcode4J needs a functional graphical 
          environment. Furthermore, if you generate SVG barcode in conjunction with Apache FOP
          you will need a graphical environment since FOP uses Batik to render the barcodes. 
          Batik needs the graphical environment to work.
        </p>
        <p>
          The work-arounds are the <link href="http://xml.apache.org/fop/graphics.html#batik">same</link> as for Apache FOP:
        </p>
        <ul>
          <li>
            If you are using JDK 1.4 or later, start it with the command line option:<br /> <code>-Djava.awt.headless=true</code> 
          </li>
          <li>
            Install an X server which provides an in-memory framebuffer without actually 
            using a screen device or any display hardware. One example is Xvfb.
          </li>
          <li>
            Install a toolkit which emulates AWT without the need for an underlying X 
            server. One example is the 
            <fork href="http://www.eteks.com/pja/en/">PJA toolkit</fork>, which is 
            free (GPL license) and comes with detailed installation instructions.
          </li>
        </ul>
      </answer>
    </faq>
  </part>
  <!-- More faqs or parts here -->
</faqs>
