This is Info file barcode.info, produced by Makeinfo version 1.68 from
the input file barcode.texinfo.

   This file is the User's Manual for the barcode library (version
0.90.3).

   This file documents the 0.90.3 release of the barcode library and
sample programs (July 1999).


File: barcode.info,  Node: Top,  Next: Overview,  Prev: (dir),  Up: (dir)

Barcode tools
*************

* Menu:

* Overview::
* The Barcode Object::
* Supported Flags::
* The API::
* The barcode Executable::


File: barcode.info,  Node: Overview,  Next: The Barcode Object,  Prev: Top,  Up: Top

Overview
********

   The "barcode" package is mainly a C library for creating bar-code
output files. It also includes a command line front-end and (in a
foreseeable future) a graphic frontend.

   The package is designed as a library because we think the main use
for barcode-generation tools is inside more featured applications. The
library addresses bar code printing as two distinct problems: creation
of bar information and actual conversion to an output format. To this
aim we use an intermediate representation for bar codes, which is
currently documented in the `ps.c' source file (not in this document).

   Note that the library and the accompanying material is released
according to the GPL license, not the LGPL one. A copy of the GPL is
included in the distribution tarball.


File: barcode.info,  Node: The Barcode Object,  Next: Supported Flags,  Prev: Overview,  Up: Top

The Underlying Data Structure
*****************************

   Every barcode-related function acts on a data structure defined in
the `barcode.h' header, which must be included by any C source file
that uses the library. The header is installed by make install.

   The definition of the data structure is included here for reference:

     struct Barcode_Item {
         int flags;         /* type of encoding and decoding */
         char *ascii;       /* malloced */
         char *partial;     /* malloced too */
         char *textinfo;    /* information about text positioning */
         char *encoding;    /* code name, filled by encoding engine */
         int width, height; /* output units */
         int xoff, yoff;    /* output units */
         int margin;        /* output units */
         double scalef;     /* requested scaling for barcode */
         int error;         /* an errno-like value, in case of failure */
     };

   The exact meaning of each field and the various flags implemented are
described in the following sections.

   Even though you won't usually need to act on the contents of this
structure, some of the functions in the library receive arguments that
are directly related to one or more of these fields.

* Menu:

* The Field List::


File: barcode.info,  Node: The Field List,  Prev: The Barcode Object,  Up: The Barcode Object

The Fields
==========

`int flags;'
     The flags are, as you may suspect, meant to specify the exact
     behaviour of the library. They are often passed as an argument to
     barcode functions and are discussed in the next section.

`char *ascii;'
`char *partial;'
`char *textinfo;'
`char *encoding;'
     These fields are internally managed by the library, and you are
     not expected to touch them if you use the provided API. All of
     them are allocated with malloc.

`int width;'
`int height;'
     They specify the width and height of the active barcode region
     (i.e., excluding the white margin), in the units used to create
     output data (for postscript they are points, 1/72th of an inch,
     0.0352 mm). The fields can be either assigned to in the structure
     or via Barcode_Position(), at your choice.  If either value or
     both are left to their default value of zero, the output engine
     will assign default values according to the specified scaling
     factor. If the specified width is bigger than needed (according to
     the scaling factor), the output barcode will be centered in its
     requested region. If either the width of the height are too small
     for the specified scale factor, the output bar code will expand
     symmetrically around the requested region.

`int xoff;'
`int yoff;'
     The fields specify offset from the coordinate origin of the output
     engine (for postscript, position 0,0 is the lower left corner of
     the page).  The fields can be either assigned to in the structure
     or via Barcode_Position(), at your choice.  The offset specifies
     where the white margin begins, not where the first bar will be
     printed. To print real ink to the specified position you should
     set margin to 0.

`int margin;'
     The white margin that will be left around the printed area of the
     bar code. The same margin is applied to all sides of the printed
     area. The default value for the margin is defined in `barcode.h'
     as BARCODE_DEFAULT_MARGIN (10).

`double scalef;'
     The enlarge or shrink value for the bar code over its default
     dimension. The width and scalef fields interact deeply in the
     creation of the output, and a complete description of the issues
     appears later in this section.

`int error;'
     The field is used when a barcode function fails to host an
     errno-like integer value.

Use of the width and scalef fields.
-----------------------------------

   A width unit is the width of the thinnest bar and/or space in the
chosen code; it defaults to 1 point if the output is postscript or
encapsulated postscript.

   Either or both the code width and the scale factor can be left
unspecified (i.e., zero). The library deals with defaults in the
following way:

Both unspecified
     If both the width and the scale factor are unspecified, the scale
     factor will default to 1.0 and the width is calculated according
     to the actual width of the bar code being printed.

Width unspecified
     If the width is not specified, it is calculated according to the
     values of scalef.

Scale factor unspecified
     If the scale factor is not specified, it will be chosen so that
     the generated bar code exactly fits the specified width.

Both specified
     The code will be printed inside the specified region according to
     the specified scale factor. It will be aligned to the left.  If,
     however, the chosen width is too small for the specific bar code
     and scaling factor, then the code will extend symmetrically to the
     left and to the right of the chosen region.


File: barcode.info,  Node: Supported Flags,  Next: The API,  Prev: The Barcode Object,  Up: Top

The Flags
*********

   The following flags are supported by version 0.90.3 of the library:

`BARCODE_ENCODING_MASK'
     The mask is used to extract the encoding-type identifier from the
     flags field.

`BARCODE_EAN'
`BARCODE_UPC'
`BARCODE_ISBN'
`BARCODE_39'
     The currently supported encoding types: EAN (13 digits, 8 digits,
     13 + 2 addon and 13 + 5 addon), UPC (UPC-A, UPC-E, UPC-A with 2 or
     5 digit addon), ISBN (with or without the 5-digit addon) and
     CODE39. *Note Supported Encodings::

`BARCODE_ANY'
     This special encoding type (represented by a value of zero, so it
     will be the default) tells the encoding procedure to look for the
     first enconding type that can deal with a textual string.
     Therefore, a 11-digit code will be printed as UPC (as well as
     6-digit, 11+2 and 11+5), a 12-digit (or 7-digit, or 12+2 or 12+5)
     as EAN13, an ISBN code (with ot without hiphens, with or without
     add-5) will be encoded in its EAN13 representation and a
     text-and-digits string will be encoded using code-39.

`BARCODE_NO_ASCII'
     Instructs the engine not to print the ascii string on output. By
     default the bar code is accompanied with an ascii version of the
     text it encodes.

`BARCODE_NO_CHECKSUM'
     Instructs the engine not to add the checksum character to the
     output. Not all the encoding types can drop the checksum; those
     where the checksum is mandatory (like EAN and UPC) just ignore the
     flag.

`BARCODE_OUTPUT_MASK'
     The mask is used to extract the output-type identifier from the
     flags field.

`BARCODE_OUT_PS'
`BARCODE_OUT_EPS'
     The currently supported encoding types: full-page postscript and
     encapsulated postscript.

`BARCODE_OUT_NOHEADERS'
     The flag instructs the printing engine not to print the header and
     footer part of the file. This makes sense for the postscript
     engine but might not make sense for other engines; such other
     engines will silently ignore the flag.


File: barcode.info,  Node: The API,  Next: The barcode Executable,  Prev: Supported Flags,  Up: Top

Funcntions Exported by the Library
**********************************

   The functions included in the barcode library are declared in the
header file barcode.h.  They perform the following tasks:

`struct Barcode_Item *Barcode_Create(char *text);'
     The function creates a new barcode object to deal with a specified
     text string.  It returns NULL in case of failure and a pointer to
     a barcode data structure in case of success.

`int Barcode_Delete(struct Barcode_Item *bc);'
     Destroy a barcode object. Always returns 0 (success)

`int Barcode_Encode(struct Barcode_Item *bc, int flags);'
     Encode the text included in the bc object. Valid flags are the
     encoding type (other flags are ignored) and BARCODE_NO_CHECKSUM
     (other flags are silently ignored); if the flag argument is zero,
     bc->flags will apply. The function returns 0 on success and -1 in
     case of error. After successfull termination the data structure
     will host the description of the bar code and its textual
     representation, after a failure the error field will include the
     reason of the failure.

`int Barcode_Print(struct Barcode_Item *bc, FILE *f, int flags);'
     Print the bar code described by bc to the specified file.  Valid
     flags are the output type, BARCODE_NO_ASCII and
     BARCODE_OUT_NOHEADERS, other flags are ignored. If any of these
     flags is zero, it will be inherited from bc->flags which therefore
     takes precedence. The function returns 0 on success and -1 in case
     of error (with bc->error set accordingly). In case of success, the
     bar code is printed to the specified file, which won't be closed
     after use.

`int Barcode_Position(struct Barcode_Item *bc, int wid, int hei, int xoff, int yoff, double scalef);'
     The function is a shortcut to assign values to the data structure.

`int Barcode_Encode_and_Print(char *text, FILE *f, int wid, int hei, int xoff, int yoff, double scalef, int flags);'
     The function deals with the whole life of the barcode object by
     calling the other functions; it uses all the spefified flags.

`int Barcode_Version(char *versionname);'
     Returns the current version as an integer number of the form major
     * 10000 + minor * 100 + release. Therefore, version 1.03.5 will be
     returned as 10305 and version 0.53 as 5300.  If the argument is
     non-null, it will be used to return the version number as a
     string. Note that the same information is available from two
     preprocessor macros: BARCODE_VERSION (the string) and
     BARCODE_VERSION_INT (the integer number).


File: barcode.info,  Node: The barcode Executable,  Prev: The API,  Up: Top

The barcode frontend program
****************************

   The barcode program is a front-end to access some features of the
library from the command line.  It is able to read user supplied
strings from the commandline or a data file (standard input by default)
and encode all of them.

* Menu:

* The Command Line::
* Supported Encodings::
* Bugs and Pending Issues::


File: barcode.info,  Node: The Command Line,  Next: Supported Encodings,  Prev: The barcode Executable,  Up: The barcode Executable

The Command Line
================

   barcode accepts the following options:

`-h'
`--help'
     Print a usage summary and exit.

`-i filename'
     Specifies a file where strings to be encoded are read from. If
     missing (and if -b is not used) it defaults to standard input.
     Each data line of the input file will be used to create one
     barcode output.

`-o filename'
     Output file. It defaults to standard output.

`-b string'
     Specifies a single "barcode" string to be encoded.  The option can
     be used multiple times in order to encode multiple strings (this
     will result in multi-page postscript output or a table of barcodes
     if -t is specified).  The strings must match the encoding chosen
     with -e and no error is printed if they don't match (this may be
     construed as a bug).

`-e encoding'
     enconding is the name of the chosen encoding format being used. It
     defaults to the value of the environment variable BARCODE_ENCODING
     or to autodetection if the environment is also unset.

`-g geometry'
     The geometry argument is of the form
     "widthxheight+xmargin+ymargin" (the margin values are optional).
     The specified values must be integer numbers and they reperesent
     print points (I plan to add support for different units, like
     inches and millimeters, but this is currently not supported). The
     argument is used to place the printoutcode on the page. Note that
     an additional white margin of 10 points is added to the printout.
     If the option is unspecified, BARCODE_GEOMETRY is looked up in the
     environment, if missing a default size and no margin (but the
     default  10 points) are used.

`-t table-geometry'
     Used to print several barcodes to a single page, this option is
     meant to be used to print stickers. The argument is of the form
     "columnsxlines+xmargin+ymargin". The two margin values are applied
     symmetrically to the page and the page is currently assumed to be
     A4 format (this is a bug, and I plan to fix it). If the option is
     not specified, BARCODE_TABLE is looked up in the environment,
     otherwise no table is printed.

`-m margin(s)'
     Specify an internal margin for each sticker in the table. The
     argument is of the form "xmargin,ymargin" and the margin is
     applied symmetrically to the sticker. If unspecified, the
     environment variable BARCODE_MARGIN is used or a default internal
     margin of 10 points is used.

`-n'
     "Numeric" output: don't print the ASCII form of the code, only the
     bars.

`-c'
     No checksum character (for encodings that allow it, like code 39,
     other codes, like UPC or EAN, ignore this option).

`-E'
     Encapsulated postscript (default is normal postscript. When the
     output is generated a EPS only one text string is encoded.

`-p pagesize'
     Spacify a non-default page size. The page size can be specified in
     millimeters, inches or points (for example: "210x297mm",
     "8.5x11in", "595x842").  If libpaper is available, you can also
     specify the page size with its name, like "A3" or "letter"
     (libpaper is a standard component of Debian GNU/Linux, but may be
     missing elsewhere). The default page size is your system-wide
     default if libpaper is there, A4 otherwise.


File: barcode.info,  Node: Supported Encodings,  Next: Bugs and Pending Issues,  Prev: The Command Line,  Up: The barcode Executable

Supported Encodings
===================

   The program encodes text strings passed either on the command line
(with -b) or retrieved from standard input. The text representation is
interpresed according to the following rules. When auto-detection of
the encoding is enabled (i.e, no explicit encoding type is specified),
the encoding types are scanned to find one that can digest the text
string.

UPC
     The UPC frontend accepts only strings made up of digits (and, if a
     supplemental encodation is used, a blank to separate it).  It
     accepts strings of 11 digits (UPC-A) or 6 digits (UPC-E).  The
     12th digit of UPC-A is the checksum and is added by the library,
     if you pass a 12-digit string it will be rejected as invalid.  For
     UPC-A, a trailing string of 2 digits or 5 digits is accepted as
     well. Thefore, valid strings look like one of the following:
     "01234567890" (UPC-A), "012345" (UPC-E), "01234567890 12" (UPC-A,
     add-2) and "01234567890 12345" (UPC-A add-5).

EAN
     The EAN frontend is similar to UPC; it accepts strings of digits,
     12 or 7 characters long, the checksum digit is added by the
     library and a string of 13 or 8 characters is rejected. The add-2
     and add-5 extension are accepted for the EAN13 encoding. Valid
     strings look like one of the following: "123456789012" (EAN-13),
     "1234567" (EAN-8), "123456789012 12" (EAN-13 with add-2) and
     "123456789012 12345" (EAN-13 with add-5).

ISBN
     ISBN numbers are encoded as EAN-13 symbols, with an optional add-5
     trailer. The ISBN frontend of the library accepts real ISBN
     numbers and deals with any hyphen and, if present, the ISBN
     checksum character before encoding data. Valid representations for
     ISBN strings are for example: "1-56592-292-1", "3-89721-122-X" and
     "3-89721-122-X 06900".

CODE 39
     The code-39 standard can encode uppercase letters, digits, the
     blank space, plus, minus, dot, star, dollar, slash, percent.  Any
     string that is only composed of such characters is accepted by the
     code-39 encoder. To avoid loosing information, the encoder refuses
     to encode mixed-case strings (a lowercase string is nonetheless
     accepted as a shortcut, but is encoded as uppercase).


File: barcode.info,  Node: Bugs and Pending Issues,  Prev: Supported Encodings,  Up: The barcode Executable

Bugs and Pending Issues.
========================

   The current management of borders/margins is far from optimal. The
"default" margin applied by the library interferes with the external
rapresentation, but I feel it is mandatory to avoid creating barcode
output with no surrounding white space (the problem is especially
relevant for EPS output).

   Code-128 should be supported



Tag Table:
Node: Top280
Node: Overview491
Node: The Barcode Object1369
Node: The Field List2749
Node: Supported Flags6475
Node: The API8581
Node: The barcode Executable11285
Node: The Command Line11737
Node: Supported Encodings15188
Node: Bugs and Pending Issues17597

End Tag Table
