<?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 Ant Task</title>
  </header>
  <body>
    <section>
      <title>Introduction</title>
      <p>
        This page describes how to generate barcodes inside
        <link href="http://ant.apache.org">Ant</link> scripts. 
      </p>
    </section>
    <section>
      <title>Using the Ant task</title>
      <p>
        Before you can use the Barcode4J task, you have to declare it in your Ant script:
      </p>
      <source><![CDATA[
  <path id="barcode4j.classpath">
    <pathelement location="${barcode4j-root}/build/barcode4j.jar"/>
    <pathelement location="${barcode4j-root}/lib/avalon-framework-4.2.0.jar"/>
  </path>

  <taskdef name="barcode" classname="org.krysalis.barcode4j.ant.BarcodeTask"
    classpathref="barcode4j.classpath"/>]]>
      </source>
      <p>
        Then you're set to produce barcodes. Here's an example:
      </p>
      <source><![CDATA[
  <barcode output="mybarcode.svg" symbol="upce" format="svg" message="1234567"/>]]>
      </source>
      <p>
        This creates an UPC-E symbol with the message "1234567" in SVG format and saves the
        generated image as "mybarcode.svg".
      </p>
      <p>
        The Ant tasks supports the following attributes/parameters:
      </p>
      <table>
        <tr>
          <th>Attribute</th>
          <th>Description</th>
          <th>Required</th>
        </tr>
        <tr>
          <td>message</td>
          <td>The barcode message.</td>
          <td>Yes</td>
        </tr>
        <tr>
          <td>output</td>
          <td>The output file.</td>
          <td>Yes</td>
        </tr>
        <tr>
          <td>symbol</td>
          <td>
            The symbology to use. Use one of the supported symbology identifiers such as
            "code128", "datamatrix" etc. These are the same as on the command-line interface.
          </td>
          <td>Yes, if you don't specify a configuration file.</td>
        </tr>
        <tr>
          <td>configurationFile</td>
          <td>
            Allows you to specify an XML configuration file (Barcode XML format) in order to
            configure the barcode generator.
          </td>
          <td>Yes, if you don't specify a symbology.</td>
        </tr>
        <tr>
          <td>format</td>
          <td>
            The requested output format. You can either use a MIME type (such as "image/png")
            or a format identifier (such as "png").
          </td>
          <td>No; defaults to "image/svg+xml".</td>
        </tr>
        <tr>
          <td>dpi</td>
          <td>
            The resolution (in dots per inch) for the generated images. Only applicable when
            generating bitmap formats.
          </td>
          <td>No; defaults to 300.</td>
        </tr>
        <tr>
          <td>bw</td>
          <td>
            Indicates whether to generate monochrome (black and white, 1 bit) bitmap images.
            Only applicable when generating bitmap formats.
          </td>
          <td>No; defaults to "true".</td>
        </tr>
      </table>
      <note>
        The "symbol" and "configurationFile" attributes are mutually exclusive!
        If you specify both, "configuration" is ignored.
      </note>
    </section>
  </body>
</document>
