\input texinfo    @c -*-texinfo-*-
%
% doc.barcode - main file for the documentation
%
%%%%

%------------------------------------------------------------------------------
%
%                         NOTE FOR THE UNAWARE USER
%                         =========================
%
%    This file is a texinfo source. It isn't the binary file of some strange
%    editor of mine. If you want ascii, you should "make barcodedoc.txt".
%
%------------------------------------------------------------------------------

%
% This is not a conventional info file...
% I use two extra features:
%       - The '%' as a comment marker, if at beg. of line ("\%" -> "%")
%       - leading blanks are allowed
%

@comment %**start of header
@setfilename barcode.info
@settitle Barcode @value{version}
@iftex
@afourpaper
@end iftex
@comment %**end of header

@setchapternewpage off

@set version 0.94
@set update-month October 1999

@finalout

@ifinfo

This file is the User's Manual for the barcode library (version
@value{version}).

@end ifinfo

@setchapternewpage odd
@titlepage
@c use the new format for titles
@title barcode @value{version}
@subtitle A library for drawing bar codes
@subtitle @value{update-month}

@author by Alessandro Rubini (@code{rubini@@@{gnu.org,prosa.it@}})

@end titlepage
@setchapternewpage off
@headings single

@ifinfo
This file documents the @value{version} release of the barcode
library and sample programs (@value{update-month}).

@node Top, Overview, (dir), (dir)
@top Barcode tools

@menu
* Overview::                    
* The Barcode Object::          
* Supported Flags::             
* The API::                     
* The barcode Executable::      
@end menu

@end ifinfo

%##########################################################################
%##########################################################################

@node Overview, The Barcode Object, Top, Top
@chapter Overview

The @dfn{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 @file{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.

%##########################################################################

@node  The Barcode Object, Supported Flags, Overview, Top
@chapter The Underlying Data Structure

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

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

@lisp
struct Barcode_Item @{
    int flags;         /* type of encoding and other flags */
    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 */
@};
@end lisp

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::              
@end menu

@node The Field List,  , The Barcode Object, The Barcode Object
@section The Fields

@table @code

@item 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 @i{barcode} functions and are discussed in the next section.

@item char *ascii;
@itemx char *partial;
@itemx char *textinfo;
@itemx 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 @i{malloc}.

@item int width;
@itemx int height;

        They specify the width and height of the @i{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 @i{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.
        
@item int xoff;
@itemx 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 @i{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 @i{margin} to 0.

@item 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
	@file{barcode.h} as @t{BARCODE_DEFAULT_MARGIN} (10).

@item double scalef;

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

@item int error;

	The field is used when a @i{barcode} function fails to host
        an @t{errno}-like integer value.

@end table


@unnumberedsubsec Use of the @i{width} and @i{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:

@table @i

@item 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.

@item Width unspecified

	If the width is not specified, it is calculated according to
	the values of @i{scalef}. 

@item 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.

@item 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.

@end table

%==========================================================================

@node Supported Flags, The API, The Barcode Object, Top
@chapter The Flags

The following flags are supported by version @value{version} of the
library:

@table @code

@item BARCODE_ENCODING_MASK

	The mask is used to extract the encoding-type identifier from
	the @i{flags} field.

@item BARCODE_EAN
@itemx BARCODE_UPC
@itemx BARCODE_ISBN
@itemx BARCODE_128B
@itemx BARCODE_128C
@itemx BARCODE_39
@itemx BARCODE_I25

	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), CODE128-B (the whole set of printable
        ASCII characters), CODE128-C (two digits encoded by each barcode
	symbol), CODE39 (alphanumeric) and "interleaved 2 of 5" (numeric).
        @xref{Supported Encodings}

@item 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 encoding 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 or without hyphens,
	with or without add-5) will be encoded in its EAN13
	representation, an even number of digits is encoded using
	CODE128C and a generic string is encoded using CODE128B. Since
        code-39 offers a much larger representation for the same
        text string, code128-b is preferred over code39 for
        alphanumeric strings.

@item 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.

@item 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.

@item BARCODE_OUTPUT_MASK

	The mask is used to extract the output-type identifier from
	the @i{flags} field.

@item BARCODE_OUT_PS
@itemx BARCODE_OUT_EPS

	The currently supported encoding types: full-page postscript
	and encapsulated postscript.

@item 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.

@end table

%##########################################################################

@node  The API, The barcode Executable, Supported Flags, Top
@chapter Functions Exported by the Library

%MANPAGE barcode.3
%M .TH BARCODE 3 "October 1999" "GNU" "GNU barcode"
%M .UC 4
%M .SH NAME
%M barcode \- a library to create and print bar codes
%M .SH SYNOPSIS
%M .B #include <barcode.h>
%M .sp
%M .BI "struct Barcode_Item *Barcode_Create(char *" text ");"
%M .br
%M .BI "int Barcode_Delete(struct Barcode_Item *" bc ");"
%M .br
%M .BI "int Barcode_Encode(struct Barcode_Item *" bc ", int " flags ");"
%M .br
%M .BI "int Barcode_Print(struct Barcode_Item *" bc ", FILE *" f ", int " flags ");"
%M .br
%M .BI "int Barcode_Position(struct Barcode_Item *" bc ", int " wid ", int " hei ", int " xoff ", int " yoff " , double " scalef ");"
%M .br
%M .BI "int Barcode_Encode_and_Print(char *" text ", FILE *" f ", int " wid ", int " hei ", int " xoff ", int " yoff ", double " scalef ", int " flags ");"
%M .br
%M .BI "int Barcode_Version(char *" versionname ");"
%M
%M .SH DESCRIPTION
%M
%M The barcode family of library functions is meant to ease
%M creation of bar-code printouts.
%M
%M The information below is extracted from the texinfo file, which is the
%M preferred source of information.

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

@table @code

@item 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.

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

@item int Barcode_Encode(struct Barcode_Item *bc, int flags);
	Encode the text included in the @i{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, @t{bc->flags} will apply. The function
	returns 0 on success and -1 in case of error. After
	successful termination the data structure will host the
	description of the bar code and its textual representation,
	after a failure the @t{error} field will include the reason of
	the failure.

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

@item 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.

@item 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 specified
	flags.

@item 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: @t{BARCODE_VERSION} (the string) and
        @t{BARCODE_VERSION_INT} (the integer number).

@end table

%MANPAGE END

%##########################################################################

@node  The barcode Executable,  , The API, Top
@chapter The @i{barcode} frontend program

%MANPAGE barcode.1
%M .TH BARCODE 1 "October 1999" "GNU" "GNU barcode"
%M .UC 4
%M .SH NAME
%M barcode \- a stand alone program to run the barcode library
%M .SH SYNOPSIS
%M .B barcode
%M [\-b - | string] [\-e encoding] [\-o - | outfile] [\-w N]
%M [\-h N] [\-x N] [\-y N] [\-l N] [\-c N]
%M .SH DESCRIPTION
%M
%M The information below is extracted from the texinfo file, which is the
%M preferred source of information.
%M .PP
The @b{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 command line or a data file (standard input by default)
and encode all of them.

%M .SH OPTIONS
%M .PP

@menu
* The Command Line::            
* Supported Encodings::         
* Bugs and Pending Issues::     
@end menu

@node  The Command Line, Supported Encodings, The barcode Executable, The barcode Executable
@section The Command Line


@b{barcode} accepts the following options:

@table @code

@item --help or -h
	Print a usage summary and exit.

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

@item -o filename
	Output file. It defaults to standard output.

@item -b string
	Specify 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{-t} is specified).  The
        strings must match the encoding chosen; if it doesn't
        match the program will print a warning to @t{stderr} and
        generate ``blank'' output (although not zero-lenght).
        Please note that a string including spaces or
        other special characters must be properly quoted.

@item -e encoding
        @b{encoding} is the name of the chosen encoding format being
	used. It defaults to the value of the environment variable
	@t{BARCODE_ENCODING} or to auto detection if the environment is
	also unset.

@item -g geometry
	The geometry argument is of the form ``@i{<width>} @t{x}
	@i{<height>} [@t{+} @i{<xmargin>} @t{+} @i{<ymargin>}]'' (with
	no intervening spaces). The margin values, if missing, default
	to 0).  The specified values must be integer numbers and they
	represent 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 printout code
	on the page. Note that an additional white margin of 10 points
	is added to the printout. If the option is unspecified,
	@t{BARCODE_GEOMETRY} is looked up in the environment, if
	missing a default size and no margin (but the default 10
	points) are used.

@item -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 ``@i{<columns>} @t{x} @i{<lines>} [@t{+} @i{<leftmargin>}
        @t{+} @i{<bottommargin>} [@t{-} @i{<rightmargin>} [@t{-}
        @i{<topmargin>}]]]'' (with no intervening spaces); if missing,
        the top and right margin will default to be the same as the
        bottom and left margin. The margins are specified in print
        points or in the chosen unit (see @t{-u} below).  If the
        option is not specified, @t{BARCODE_TABLE} is looked up in the
        environment, otherwise no table is printed and each barcode
        will get its own page.

@item -m margin(s)
	Specifies an internal margin for each sticker in the
	table. The argument is of the form
	``@i{<xmargin>}@t{,}@i{<ymargin>}'' and the margin is applied
	symmetrically to the sticker. If unspecified, the environment
	variable @t{BARCODE_MARGIN} is used or a default internal
	margin of 10 points is used.

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

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

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

@item -p pagesize
	Specify a non-default page size. The page size can be specified
        in millimeters, inches or plain numbers (for example: "@t{210x297mm}",
        "@t{8.5x11in}", "@t{595x842}"). A page specification as numbers
	will be interpreted according to the current unit specification
	(see @t{-u} below). If libpaper is available,
        you can also specify the page size with its name, like "@t{A3}"
        or "@t{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.

@item -u unit

	Choose the unit used in size specifications. Accepted values
	are ``mm'', ``cm'', ``in'' and ``pt''. By default, the program
	will check @t{BARCODE_UNIT} in the environment, and assume
	points otherwise (this behaviour is compatible with 0.92 and
	previous versions. If @t{-u} appears more than once, each
	instance will modified the behaviour for the arguments at its
	right, as the command line is processes left to right. The
	program internally works with points, and any size is
	approximated to the nearest multiple of one point. The @t{-u}
	option affect @t{-g} (geometry), @t{-t} (table) and @t{-p}
	(page size).
	
@end table

%M .SH ENCODING TYPES
%M .PP

@node  Supported Encodings, Bugs and Pending Issues, The Command Line, The barcode Executable
@section Supported Encodings

The program encodes text strings passed either on the command line
(with -b) or retrieved from standard input. The text representation is
interpreted 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.

@table @var

@item UPC

	The UPC frontend accepts only strings made up of digits (and,
	if a supplemental encoding 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. Therefore, valid strings look like one of
	the following: ``@t{01234567890}'' (UPC-A), ``@t{012345}''
	(UPC-E), ``@t{01234567890 12}'' (UPC-A, add-2) and
	``@t{01234567890 12345}'' (UPC-A add-5).

@item 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:
	``@t{123456789012}'' (EAN-13), ``@t{1234567}'' (EAN-8),
	``@t{123456789012 12}'' (EAN-13 with add-2) and
	``@t{123456789012 12345}'' (EAN-13 with add-5).

@item 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:
	``@t{1-56592-292-1}'', ``3-89721-122-X'' and ``3-89721-122-X
	06900''.

@item code 128-B

	This encoding can represent all of the printing ASCII
        characters, from the space (32) to DEL (127). The checksum
        digit is mandatory in this encoding.

@item code 128-C

	The ``C'' variation of Code-128 uses Code-128 symbols to
	represent two digits at a time (Code-128 is made up of 104
	symbols whose interpretation is controlled by the start symbol
	being used). Code 128-C is thus the most compact way to
	represent any even number of digits. The encoder refuses to
	deal with an odd number of digits because the caller is
	expected to provide proper padding to an even number of
	digits. (Since Code-128 includes control symbols to switch
	charset, it is theoretically possible to represent the odd
	digit as a Code 128-A or 128-B symbol, but this tool doesn't
	currently implement this option).

@item 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).

@item interleaved 2 of 5

	This encoding can only represent an even number of digits
        (odd digits are represented by bars, and even digits by the
        interleaving spaces). The name stresses the fact that two
        of the five items (bars or spaces) allocated to each symbol
        are wide, while the rest are narrow. The checksum digit is
        optional (can be disabled via @t{BARCODE_NO_CHECKSUM}).
        Since the number of digits, including the checksum, must be even,
        a leading zero is inserted in the string being encoded if needed
        (this is specifically stated in the specs I have access to).

@end table

%M .SH BUGS

@node  Bugs and Pending Issues,  , Supported Encodings, The barcode Executable
@section 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
representation, but I feel it is mandatory to avoid creating barcode
output with no surrounding white space (the problem is especially
relevant for EPS output).

Code128-A should be supported.

%M .SH "SEE ALSO"
%M \fBbarcode(3)\fP
%M
%M .SH AUTHORS
%M Alessandro Rubini, Prosa s.r.l <rubini@prosa.it> (maintainer)
%M .PP
%M Michele Comitini, Glisco s.a.s. <mcm@glisco.it> (several contributions)
%MANPAGE END

@iftex
@contents
@end iftex

@bye