<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" "document-v11.dtd">
<document>
  <header>
    <title>Using the Command Line Interface</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 use the command line interface that comes with 
        <strong>Barcode4J</strong>.
      </p>
    </section>
    <section>
      <title>Features</title>
      <p>
        The command line interface has the following features:
      </p>
      <ul>
        <li>Output to the console or to a file</li>
        <li>Output formats: SVG, EPS, bitmap formats</li>
        <li>Ability to set the same symbology properties as in the XSLT or XSL-FO extensions (via a configuration file)</li>
        <li>Ability to set the resolution and color settings for the bitmaps</li>
      </ul>
    </section>
    <section>
      <title>Running the command line application</title>
      <p>
        The main class for the command line interface is <code>org.krysalis.barcode4j.cli.Main</code>. 
        Either setup the classpath manually (-cp option) or use the barcode.bat batch file (Windows only).
      </p>
      <p>Required libraries are:</p>
      <ul>
        <li><code>barcode4j.jar</code> (from the <code>build/</code> directory)</li>
        <li><code>avalon-framework-4.2.0.jar</code> (<fork href="ext:avalon">Apache Avalon Framework</fork>, from the <code>lib/</code> directory)</li>
        <li><code>commons-cli-1.0.jar</code> (<fork href="ext:commons-cli">Apache Jakarta Commons CLI</fork>, from the <code>lib/</code> directory)</li>
      </ul>
      <p>An example:</p>
      <source><![CDATA[
Windows:
java -cp build\barcode4j.jar;lib\avalon-framework-4.1.5.jar;lib\commons-cli-1.0.jar
    org.krysalis.barcode4j.cli.Main <parameters>

Unix:
java -cp build/barcode4j.jar:lib/avalon-framework-4.1.5.jar:lib/commons-cli-1.0.jar
    org.krysalis.barcode4j.cli.Main <parameters>]]></source>
    </section>
    <section>
      <title>Parameters</title>
      <p>Calling the Command Line Interface without parameters brings up the help screen:</p>
      <source><![CDATA[
Barcode4J command-line application, Version 2.0

usage: java -jar barcode4j.jar [-v] [[-s <symbology>]|[-c <cfg-file>]] [-f
            <format>] [-d <dpi>] [-bw] [-o <file>] <message>
    --bw                (for bitmaps) create monochrome (1-bit) image
                        instead of grayscale (8-bit)
 -s,--symbol <name>     the barcode symbology to select (default settings,
                        use -c if you want to customize)
 -c,--config <file>     the config file
 -d,--dpi <integer>     (for bitmaps) the image resolution in dpi
                        Default: 300
 -f,--format <format>   the output format: MIME type or file extension
                        Default: image/svg+xml (SVG)
 -o,--output <file>     the output filename
 -v,--verbose           enable debug output
Valid output formats:
SVG: image/svg+xml, svg
EPS: image/x-eps, eps
PNG: image/x-png, png
TIFF: image/tiff, tiff, tif (unavailable)
JPEG: image/jpeg, jpeg, jpg
GIF: image/gif, gif (unavailable)
If -o is omitted the output is written to stdout.]]></source>
      <note>You'll notive the "(unavailable)" notice above. Not all image formats are available in every environment.</note>
      <p>
        Hopefully, the above is self-explanatory, so we just provide a few examples.
      </p>
      <section>
        <title>Example 1</title>
        <source><![CDATA[
java -cp <classpath> org...cli.Main -s code128 "MyMessage"]]></source>
        <p>
          This creates SVG output (because SVG is default if no format is given). The 
          SVG is written to the console due to the absence of an output filename. The 
          symbology used is "Code 128" (-s code128).
        </p>
      </section>
      <section>
        <title>Example 2</title>
        <source><![CDATA[
java -cp <classpath> org...cli.Main -o barcode.eps -f eps -s ean13 "008888650997"]]></source>
        <p>
          This creates an EAN-13 (-f ean13) barcode that is written to a file (-o) in EPS format (-f eps). 
        </p>
      </section>
      <section>
        <title>Example 3</title>
        <source><![CDATA[
java -cp <classpath> org...cli.Main -o barcode.png -f png --bw -d 600 -s ean13 "008888650997"]]></source>
        <p>
          This creates the same barcode as above but generates a monochrome (--bw) PNG 
          bitmap (-f png) instead. The resolution is set to 600dpi (-d 600).
        </p>
      </section>
    </section>
    <section>
      <title>Tweaking the barcode settings</title>
      <p>
        Often, you will need to change the barcode settings because the default values don't provide
        the desired result. In this case you have to provide a little XML file with the configuration
        for the barcode symbology. The XML format used there is again the same 
        <link href="barcode-xml.html">Barcode XML</link> as used everywhere else.
      </p>
      <p>Here's an example configuration file (for example: barcode-cfg.xml):</p>
        <source><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<barcode>
  <code128>
    <height>2cm</height>
    <module-width>0.5mm</module-width>
  </code128>
</barcode>]]></source>
      <p>
        The above sets up a Code 128 barcode. To generate the barcode you use the -c parameter 
        instead of the -s parameter. The first example again, this time with a -c parameter:
      </p>
        <source><![CDATA[
java -cp <classpath> org...cli.Main -c barcode-cfg.xml "MyMessage"]]></source>
    </section>
  </body>
</document>
