<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
  <header>
    <title>Troubleshooting</title>
    <authors>
      <person id="jmaerki" name="Jeremias Märki" email="jmaerki@users.sourceforge.net"/>
    </authors>
  </header>
  <body>
    <section id="printing-quality">
      <title>What if my barcode scanner can't read the barcode?</title>
      <p>
        If a barcode is unreadable by a barcode scanner it doesn't necessarily mean 
        that this software is buggy. So before you send a bug report please consult 
        the following checklist of things that can go wrong:
      </p>
      <ul>
        <li>
          Check the specifications of your barcode scanner to find out if the barcode
          you wanted to scan is even supported.
        </li>
        <li>
          Check your <link href="site:current/barcode-xml/general/structure">barcode settings</link>. 
          Make sure the module widths, for example, are 
          within the specs. Barcode4J can not always detect in advance that
          a barcode will be unreadable.
        </li>
        <li>
          Depending on your printer you might need to adjust the 
          <link href="site:current/barcode-xml/general/structure">barcode settings</link> 
          (<em>e.g.</em>, wide factor or module width) to get a better result.
          If the printer resolution compared to the barcode size is poor (<em>e.g.</em>, 
          laser printers generally output higher resolution than inkjet printers), you will
          run into problems.
        </li>
        <li>
          Sometimes you need to play with the resolution and module width 
          settings to get the best result.</li>
        <dl>
          <dt><strong>Example:</strong></dt>
          <dd>The minimum <em>module width</em> 
            can be computed by 1&#160;/&#160;[resolution].
            Example: 1&#160;/&#160;300dpi&#160;=&#160;0.0033333333in. 
          This results in narrow bars being exactly one pixel in width. For 
          barcodes with a wide-factor parameter (like Codabar) you need to choose 
          a non-fractional value in this case (2 or 3, not 2.5), because there is 
          no "half a pixel" in bitmaps. If your values are <em>too</em> small, the barcode
          scanner won&apos;t be able to detect the difference between narrow and wide bars.</dd>
        </dl>
        <li>
          Here's PDF that illustrates the result of various settings related to bitmap resolutions vs. module widths.
          Compare the various examples to see the subtle differences which can decide whether a barcode can be read or not:
          <fork href="barcode-resolution.pdf">barcode-resolution.pdf <img src="skin/images/pdfdoc.gif" alt="PDF document"/></fork> (around 13KB)
        </li>
        <li>
          Make sure your printer is in good operating condition. Print a test page 
          to see if you have any missing areas or vertical lines. If only one element
          of a 1D barcode is narrower than it should be (<em>e.g.</em>, because the printer 
          doesn't work properly) the barcode will no longer be readable.
        </li>
        <li>
          Be careful when printing bitmap barcodes from a browser. You can't just
          reduce the resolution to get the desired size. It is better to increase the 
          resolution and use HTML to scale down the bitmap or ...(see next point)
        </li>
        <li>
          Avoid JPEG as target format for your barcodes (<em>e.g.</em> GIF, PNG or TIFF are better). 
          JPEG is a lossy compression
          format and contrast will suffer and thus degrading the readability of the 
          generated barcode. 
        </li>
        <li>
          When possible, favor a vector format like SVG or EPS over a bitmap so you can profit from the printer's maximum resolution
          as well as a nicer-looking human-readable message. Of course, if your printer is a fax at only 150dpi, you may still need to tweak
          your barcode settings.
        </li>
        <li>
          Make sure you respect the quiet zones (defined in the individual barcode 
          specs) when you place the barcode on a page.
        </li>
        <li>
          Make sure the barcode doesn't get clipped or overwritten by text.
        </li>
        <li>
          Make sure you use checksums properly. For some barcodes, you can supply a
          checksum yourself in the message or let Barcode4J calculate it. If
          you do it yourself make sure the calculation is correct.
        </li>
      </ul>
    </section>
    <section id="wrong-characters">
      <title>What if my barcode scanner sends back some incorrect characters?</title>
      <p>
        Barcode scanners connected to the the keyboard cable send the barcode to the
        computer as simulated key presses. You need to make sure your barcode
        scanner is correctly set up with the same character set as your keyboard.
        Please consult the manual for your barcode scanner to find out how to do that.
      </p>
    </section>
  </body>
</document>
