Adding upstream version 0.23.93.upstream/0.23.93upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

3 files changed, 614 insertions, 0 deletions

diff --git a/doc/ref/commonoptions.xml b/doc/ref/commonoptions.xml
new file mode 100644
index 0000000..3552025
--- /dev/null
+++ b/doc/ref/commonoptions.xml
@@ -0,0 +1,165 @@
+<varlistentry>
+  <term><option>-h</option></term>
+  <term><option>--help</option></term>
+  <listitem>
+    <simpara>Print a short help message describing command line
+    options to standard output and exit</simpara>
+  </listitem>
+</varlistentry>
+
+<varlistentry>
+  <term><option>--version</option></term>
+  <listitem>
+    <simpara>Print program version information to standard output and
+    exit</simpara>
+  </listitem>
+</varlistentry>
+
+<varlistentry>
+  <term><option>-v</option></term>
+  <term><option>--verbose<optional>=<replaceable
+          class="parameter">n</replaceable></optional></option></term>
+  <listitem>
+    <simpara>Increase debug output level.  Multiple
+      <option>-v</option> options create more spew.  Alternatively
+      specify <replaceable class="parameter">n</replaceable> to
+      set the debug level directly
+    </simpara>
+  </listitem>
+</varlistentry>
+
+<varlistentry>
+  <term><option>-S<optional><replaceable
+          class="parameter">symbology</replaceable>.</optional><replaceable
+        class="parameter">config</replaceable><optional>=<replaceable
+          class="parameter">value</replaceable></optional></option></term>
+  <term><option>--set <optional><replaceable
+          class="parameter">symbology</replaceable>.</optional><replaceable
+        class="parameter">config</replaceable><optional>=<replaceable
+          class="parameter">value</replaceable></optional></option></term>
+  <listitem>
+    <simpara>Set decoder configuration option <replaceable
+      class="parameter">config</replaceable> for <replaceable
+      class="parameter">symbology</replaceable> to <replaceable
+      class="parameter">value</replaceable>.  <replaceable
+      class="parameter">value</replaceable> defaults to 1 if omitted.
+      <replaceable class="parameter">symbology</replaceable> is one of
+      <option>ean13</option>, <option>ean8</option>,
+      <option>upca</option>, <option>upce</option>,
+      <option>isbn13</option>, <option>isbn10</option>,
+      <option>i25</option>, <option>codabar</option>, <option>code39</option>,
+      <option>code93</option>, <option>code128</option>,
+      <option>qrcode</option> or the special value <option>*</option>.
+      If <replaceable class="parameter">symbology</replaceable> is
+      omitted or <option>*</option>, the <replaceable
+      class="parameter">config</replaceable> will be set for all
+      applicable symbologies.  These are the currently recognized
+      <replaceable class="parameter">config</replaceable>s.  Prefix a
+      config with "no-" to negate it.  Not all configs are appropriate
+      for every symbology.</simpara>
+
+    <variablelist>
+      <varlistentry>
+        <term><option>enable</option></term>
+        <listitem>
+          <simpara>Control decoding/reporting of a symbology.  For
+            symbologies which are just subsets of <option>ean13</option>
+            (<option>upca</option>, <option>upce</option>,
+            <option>isbn13</option>, <option>isbn10</option>), this
+            config controls whether the subsets are detected and
+            reported as such.  These special cases are disabled by
+            default, all other symbologies default to enabled</simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>disable</option></term>
+        <listitem>
+          <simpara>Antonym for <option>enable</option></simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>emit-check</option></term>
+        <listitem>
+          <simpara>Control whether check digits are included in the
+            decoded output.  Enabled by default.  This config does not
+            apply for <option>code128</option>, which never returns the
+            check digit.  It also not apply for cases where the check
+            digit is disabled (see <option>add-check</option>).  Check
+            digits are currently not implemented for
+            <option>i25</option> or <option>code39</option></simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>add-check</option></term>
+        <listitem>
+          <simpara>Enable decode and verification of a check digit for
+            symbologies where it is optional: this will include
+            <option>code39</option> and <option>i25</option>, neither of
+            which implements the check digit yet</simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>ascii</option></term>
+        <listitem>
+          <simpara>Enable escape sequences that encode the full ASCII
+            character set.  This would apply to <option>code39</option>,
+            except that it's not implemented either...</simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>position</option></term>
+        <listitem>
+          <simpara>Enable collection of symbol position information.
+          Enabled by default.  Currently, the position information is
+          unusable, so you can save a few cycles by disabling
+          this.</simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>test-inverted</option></term>
+        <listitem>
+          <simpara>Specially for QR code images, sometimes the image
+          is inverted, e. g. lines are written in white instead of black.
+          This option makes ZBar to invert the image and parse again, in
+          case it fails using the normal order. Enabling it affects all
+          decoders.</simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>min-length=<replaceable class="parameter">n</replaceable></option></term>
+        <term><option>max-length=<replaceable class="parameter">n</replaceable></option></term>
+        <listitem>
+          <simpara>Bound the number of decoded characters in a valid symbol.
+          If a decode result is outside the configured min/max range
+          (inclusive), it will not be reported.  Set to 0 to disable the
+          corresponding check.  This setting applies to variable-length
+          symbologies: <option>i25</option>, <option>codabar</option>,
+          <option>code39</option>, <option>code128</option> and
+          <option>pdf417</option>. <option>min-length</option> defaults to 6
+          for <option>i25</option> and 1 for <option>code39</option> (per Code
+          39 autodiscrimination recommendation); all others default to
+          0</simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>x-density=<replaceable class="parameter">n</replaceable></option></term>
+        <term><option>y-density=<replaceable class="parameter">n</replaceable></option></term>
+        <listitem>
+          <simpara>Adjust the density of the scanner passes.  Lower values
+          scan more of the image at the cost of decreased performance.
+          Setting to 0 disables scanning along that axis.  Defaults are both
+          1.</simpara>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+  </listitem>
+</varlistentry>
diff --git a/doc/ref/zbarcam.xml b/doc/ref/zbarcam.xml
new file mode 100644
index 0000000..69ad593
--- /dev/null
+++ b/doc/ref/zbarcam.xml
@@ -0,0 +1,207 @@
+<refentry xml:id="zbarcam"
+  xmlns:xlink="http://www.w3.org/1999/xlink">
+
+  <refmeta>
+    <refentrytitle>zbarcam</refentrytitle>
+    <manvolnum>1</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>zbarcam</refname>
+
+    <refpurpose>scan and decode bar codes from a video device
+    </refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>zbarcam</command>
+      <arg><option>-qv</option></arg>
+      <arg><option>--quiet</option></arg>
+      <arg><option>--nodisplay</option></arg>
+      <arg><option>--xml</option></arg>
+      <arg><option>--verbose<arg>=<replaceable
+      class="parameter">n</replaceable></arg></option></arg>
+      <arg><option>--prescale=<replaceable
+          class="parameter">W</replaceable>x<replaceable
+          class="parameter">H</replaceable></option></arg>
+      <arg><option>-S<optional><replaceable
+          class="parameter">symbology</replaceable>.</optional><replaceable
+          class="parameter">config</replaceable><optional>=<replaceable
+          class="parameter">value</replaceable></optional></option></arg>
+      <arg><option>--set <optional><replaceable
+          class="parameter">symbology</replaceable>.</optional><replaceable
+          class="parameter">config</replaceable><optional>=<replaceable
+          class="parameter">value</replaceable></optional></option></arg>
+      <arg><replaceable class="parameter">device</replaceable></arg>
+    </cmdsynopsis>
+
+    <cmdsynopsis>
+      <command>zbarcam</command>
+      <group choice="req">
+        <arg choice="plain"><option>-h</option></arg>
+        <arg choice="plain"><option>--help</option></arg>
+        <arg choice="plain"><option>--version</option></arg>
+      </group>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Description</title>
+
+    <para><command>zbarcam</command> scans a video4linux video source
+    (eg, a webcam) for bar codes and prints any decoded data to the
+    standard output.  The video stream is also displayed to the
+    screen. </para>
+
+    <para><replaceable class="parameter">device</replaceable> is the
+    path to the video4linux (version 1 or 2) character device special
+    file (major number 81 and minor number 0 thru 63).  It defaults to
+    <filename>/dev/video0</filename></para>
+
+    <para>The underlying library currently supports EAN-13 (including
+    UPC and ISBN subsets), EAN-8, DataBar, DataBar Expanded, Code 128,
+    Code 93, Code 39, Codabar, Interleaved 2 of 5 and QR Code symbologies.
+    The specific type of each detected symbol is printed with the decoded
+    data.</para>
+
+  </refsection>
+
+  <refsection>
+    <title>Options</title>
+
+    <para>This program follows the usual GNU command line syntax.
+    Single letter options may be bundled, long options start with two
+    dashes (`-').</para>
+
+    <variablelist>
+      &refcommonoptions;
+
+      <varlistentry>
+        <term><option>-q</option></term>
+        <term><option>--quiet</option></term>
+        <listitem>
+          <simpara>Quiet operation; disable the audible beep otherwise
+          emitted when a symbol is decoded</simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--nodisplay</option></term>
+        <listitem>
+          <simpara>Disable output video window.  Video input will be
+          scanned until the program is interrupted or otherwise
+          signaled</simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--xml</option></term>
+        <listitem>
+          <simpara>Stream results using an XML output format.  This
+          format wraps the raw data from the symbol with information
+          about the scan in an easy to parse format.  The latest
+          schema is available from <link xlink:href="http://zbar.sourceforge.net/2008/barcode.xsd"/></simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--raw</option></term>
+        <listitem>
+          <simpara>Use raw symbol data output format.  This format
+          prints symbol data separated by newlines without the
+          additional symbology type information that is printed by
+          default</simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--prescale=<replaceable
+          class="parameter">W</replaceable>x<replaceable
+          class="parameter">H</replaceable></option></term>
+        <listitem>
+          <simpara>Request video input scaling from the camera driver.
+          Possibly useful for reducing huge frames to achieve a higher
+          frame rate.  Note that the driver may adjust or completely
+          ignore the scaling request</simpara>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <para>Scan for barcodes using the second video device and pipe the
+    resulting data through a script that searches for each code in a
+    database and does something useful with them:
+
+      <screen><command>zbarcam</command> <filename>/dev/video1</filename> | <command>upcrpc.py</command></screen>
+
+    The <command>upcrpc.py</command> example script included in the
+    <filename>examples/</filename> subdirectory of the distribution
+    will make an XMLRPC call to a popular internet UPC database and
+    print the product description if found.</para>
+
+    <para>Scan for barcodes using the default video device and stream
+    results to stdout in XML format, also disable recognition of
+    Interleaved 2 of 5 codes to prevent confusion with other
+    symbologies or background noise:
+
+      <screen><command>zbarcam</command> <option>--xml</option> <option>-Si25.disable</option></screen>
+    </para>
+
+    <para>Scan only for Code 39, without using the preview window -
+    maybe for a fixed installation.  To enable only Code 39, first all
+    symbologies are disabled, then Code 39 is re-enabled:
+
+      <screen><command>zbarcam</command> <option>--nodisplay</option> <option>-Sdisable</option> <option>-Scode39.enable</option></screen>
+    </para>
+  </refsection>
+
+  <refsection>
+    <title>Exit Status</title>
+
+    <para><command>zbarcam</command> returns an exit code to indicate the
+    status of the program execution. Current exit codes are:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>0</term>
+        <listitem>
+          <para>Successful program completion.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>1</term>
+        <listitem>
+          <para>An error occurred.  This includes bad arguments and I/O
+          errors.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>2</term>
+        <listitem>
+          <para>A fatal error occurred.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+    <para><xref linkend="zbarimg"/></para>
+    <para><link xlink:href="http://zbar.sf.net/"/></para>
+  </refsection>
+
+  <refsection>
+    <title>Bugs</title>
+
+    <para>See <link xlink:href="http://sf.net/tracker/?group_id=189236&amp;atid=928515"/></para>
+
+  </refsection>
+
+</refentry>
diff --git a/doc/ref/zbarimg.xml b/doc/ref/zbarimg.xml
new file mode 100644
index 0000000..572bea9
--- /dev/null
+++ b/doc/ref/zbarimg.xml
@@ -0,0 +1,242 @@
+<refentry xml:id="zbarimg"
+  xmlns:xlink="http://www.w3.org/1999/xlink">
+
+  <refmeta>
+    <refentrytitle>zbarimg</refentrytitle>
+    <manvolnum>1</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>zbarimg</refname>
+
+    <refpurpose>scan and decode bar codes from image file(s)
+    </refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>zbarimg</command>
+      <arg><option>-qv</option></arg>
+      <arg><option>--polygon</option></arg>
+      <arg><option>--quiet</option></arg>
+      <arg><option>--verbose<arg>=<replaceable
+      class="parameter">n</replaceable></arg></option></arg>
+      <sbr/>
+      <group choice="req" rep="repeat">
+        <arg choice="plain"><option>-dD</option></arg>
+        <arg choice="plain"><option>--display</option></arg>
+        <arg choice="plain"><option>--nodisplay</option></arg>
+        <arg choice="plain"><option>--xml</option></arg>
+        <arg choice="plain"><option>--noxml</option></arg>
+        <arg choice="plain"><option>-S<optional><replaceable
+            class="parameter">symbology</replaceable>.</optional><replaceable
+            class="parameter">config</replaceable><optional>=<replaceable
+            class="parameter">value</replaceable></optional></option></arg>
+        <arg choice="plain"><option>--set <optional><replaceable
+            class="parameter">symbology</replaceable>.</optional><replaceable
+            class="parameter">config</replaceable><optional>=<replaceable
+            class="parameter">value</replaceable></optional></option></arg>
+        <arg choice="plain"><replaceable>image</replaceable></arg>
+      </group>
+    </cmdsynopsis>
+
+    <cmdsynopsis>
+      <command>zbarimg</command>
+      <group choice="req">
+        <arg choice="plain"><option>-h</option></arg>
+        <arg choice="plain"><option>--help</option></arg>
+        <arg choice="plain"><option>--version</option></arg>
+      </group>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Description</title>
+
+    <para>For each specified
+    <filename><replaceable>image</replaceable></filename> file
+    <command>zbarimg</command> scans the image for bar codes and
+    prints any decoded data to stdout.  Images may optionally be
+    displayed to the screen.</para>
+
+    <para>The underlying library currently supports EAN-13 (including
+    UPC and ISBN subsets), EAN-8, DataBar, DataBar Expanded, Code 128,
+    Code 93, Code 39, Codabar, Interleaved 2 of 5 and QR Code symbologies.
+    The specific type of each detected symbol is printed with the decoded
+    data.</para>
+
+    <para>Note that "<filename><replaceable>image</replaceable></filename>"
+
+    in this context refers to any format supported by ImageMagick,
+    including many vector formats such as PDF and PostScript.  Keep in
+    mind that vector formats are rasterized before scanning; manually
+    rasterize vector images before scanning to avoid unintentionally
+    corrupting embedded barcode bitmaps.</para>
+
+  </refsection>
+
+  <refsection>
+    <title>Options</title>
+
+    <para>This program follows the usual GNU command line syntax.
+    Single letter options may be bundled, long options start with two
+    dashes (`-').</para>
+
+    <variablelist>
+      &refcommonoptions;
+
+      <varlistentry>
+        <term><option>--polygon</option></term>
+        <listitem>
+          <simpara>Ouput points of the polygon containing the code bar.
+          Using a format compatible with The &lt;polygon&gt; element
+          of the Scalable Vector Graphics (SVG) markup language</simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-q</option></term>
+        <term><option>--quiet</option></term>
+        <listitem>
+          <simpara>Quiet operation; only output decoded symbol data.
+          specifically this disables the statistics line printed (to
+          stderr) before exiting, as well as the warning message
+          printed (also to stderr) when no barcodes are found in an
+          image</simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>-d</option></term>
+        <term><option>--display</option></term>
+        <term><option>-D</option></term>
+        <term><option>--nodisplay</option></term>
+        <listitem>
+          <simpara>Enable/disable display of subsequent
+          <filename><replaceable>image</replaceable></filename> files,
+          until next <option>--display</option> or
+          <option>--nodisplay</option> is encountered.  This option
+          may appear multiple times to enable display of specific
+          images.  Image display is disabled by default</simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--xml</option></term>
+        <term><option>--noxml</option></term>
+        <listitem>
+          <simpara>Enable/disable result output using an XML format.
+          This format wraps the raw data from the symbol with
+          information about the scan (such as page indices) in an
+          easy to parse format.  The latest schema is available from
+          <link xlink:href="http://zbar.sourceforge.net/2008/barcode.xsd"/>.</simpara>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--raw</option></term>
+        <listitem>
+          <simpara>Enable raw symbol data output.  This format prints symbol
+          data separated by newlines without the additional symbology type
+          information that is printed by default</simpara>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>Examples</title>
+
+    <para>Scan a PNG image of a UPC bar code symbol and pass
+    resulting data to a script that searches for the code in a
+    database and does something useful with it:
+
+    <screen><command>zbarimg</command> <filename>product.png</filename> | <command>upcrpc.py</command></screen>
+
+    The <command>upcrpc.py</command> example script included in the
+    <filename>examples/</filename> subdirectory of the distribution
+    will make an XMLRPC call to a popular internet UPC database and
+    print the product description if found.</para>
+
+    <para>Scan a JPEG image containing several barcodes and display
+    the image in a window, also disabling recognition of Interleaved 2
+    of 5 codes to prevent confusion with other symbologies or
+    background noise:
+
+      <screen><command>zbarimg</command> <option>--display</option> <option>-Si25.disable</option> <filename>label.jpg</filename></screen>
+    </para>
+
+    <para>Look in a scanned document only for Code 39, using XML
+    output format so the page numbers are available.  To enable only
+    Code 39, first all symbologies are disabled, then Code 39 is
+    re-enabled:
+
+      <screen><command>zbarimg</command> <option>--xml</option> <option>-Sdisable</option> <option>-Scode39.enable</option> <filename>scan.tiff</filename></screen>
+    </para>
+  </refsection>
+
+  <refsection>
+    <title>Exit Status</title>
+
+    <para><command>zbarimg</command> returns an exit code to indicate the
+    status of the program execution. Current exit codes are:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>0</term>
+        <listitem>
+          <para>Barcodes successfully detected in all images. Warnings may
+          have been generated, but no errors.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>1</term>
+        <listitem>
+          <para>An error occurred while processing some image(s).  This
+          includes bad arguments, I/O errors and image handling errors from
+          ImageMagick.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>2</term>
+        <listitem>
+          <para>ImageMagick fatal error.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>3</term>
+        <listitem>
+          <para>The user quit the program before all images were scanned.
+          Only applies when running in interactive mode
+          (with <option>--display</option>)</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>4</term>
+        <listitem>
+          <para>No barcode was detected in one or more of the images.  No
+          other errors occurred.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+    <para><xref linkend="zbarcam"/></para>
+    <para><link xlink:href="http://zbar.sf.net/"/></para>
+  </refsection>
+
+  <refsection>
+    <title>Bugs</title>
+
+    <para>See <link xlink:href="http://sf.net/tracker/?group_id=189236&amp;atid=928515"/></para>
+
+  </refsection>
+
+</refentry>