--- /dev/null
+\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.98
+@set update-month March 2002
+
+@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})
+
+@end titlepage
+@setchapternewpage off
+@headings single
+
+
+@node Top, Overview, (dir), (dir)
+@top Barcode tools
+
+This file documents version @value{version} of the barcode
+library and sample programs (@value{update-month}).
+
+@menu
+* Overview::
+* The Barcode Object::
+* Supported Flags::
+* The API::
+* The barcode Executable::
+* Supported Encodings::
+* PCL Output::
+* Bugs and Pending Issues::
+@end menu
+
+
+%##########################################################################
+%##########################################################################
+
+@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 placement */
+ 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::
+* The Intermediate Representation::
+@end menu
+
+%--------------------------------------------------------------------------
+@node The Field List, The Intermediate Representation, 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.352 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 The Intermediate Representation, , The Field List, The Barcode Object
+@section The Intermediate Representation
+
+The encoding functions print their output into the @t{partial} and
+@t{texinfo} fields of the barcode data structure. Those fields, together
+with position information, are then used to generate actual output.
+This is an informal description of the intermediate format.
+
+The first char in @t{partial} tells how much extra space to add to the
+left of the bars. For EAN-13, it is used to leave space to print the
+first digit, other codes may have '0' for no-extra-space-needed.
+
+The next characters are alternating bars and spaces, as multiples of the
+base dimension which is 1 unless the code is rescaled. Rescaling is
+calculated as the ratio from the requested width and the calculated
+width. Digits represent bar/space dimensions. Lower-case letters
+represent those bars that should extend lower than the others: 'a' is
+equivalent to '1', 'b' is '2' and so on up to 'i' which is equivalent to
+'9'. Other letters will be used for encoding-specific meanings, as soon
+as I implement them.
+
+The @t{textinfo} string is made up of fields @t{%lf:%lf:%c} separated by
+blank space. The first integer is the x position of the character,
+the second is the font size (before rescaling) and the char item is
+the character to be printed.
+
+Both the @t{partial} and @t{textinfo} strings may include ``@t{-}'' or
+``@t{+}'' as special characters (in @t{textinfo} the char should be a
+stand-alone word). They state where the text should be printed: below
+the bars (``@t{-}'', default) or above the bars. This is used, for
+example, to print the add-5 and add-2 codes to the right of UPC or EAN
+codes (the add-5 extension is mostly used in ISBN codes).
+
+
+
+
+%==========================================================================
+
+@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_128
+@itemx BARCODE_128RAW
+@itemx BARCODE_39
+@itemx BARCODE_I25
+@itemx BARCODE_CBR
+@itemx BARCODE_MSI
+@itemx BARCODE_PLS
+@itemx BARCODE_93
+
+ The currently supported encoding types: EAN (13 digits, 8
+ digits, 13 + 2 add-on and 13 + 5 add-on), UPC (UPC-A, UPC-E,
+ UPC-A with 2 or 5 digit add-on), ISBN (with or without the
+ 5-digit add-on), CODE128-B (the whole set of printable
+ ASCII characters), CODE128-C (two digits encoded by each barcode
+ symbol), CODE128 (all ASCII values), a ``raw-input'' pseudo-code
+ that generates CODE128 output, CODE39 (alphanumeric),
+ "interleaved 2 of 5" (numeric), Codabar (numeric plus a few
+ symbols), MSI (numeric) and Plessey (hex digits).
+ @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
+@itemx BARCODE_OUT_PCL
+@itemx BARCODE_OUT_PCL_III
+
+ The currently supported encoding types: full-page postscript
+ and encapsulated postscript; PCL (print command language, for
+ HP printers) and PCL-III (same as PCL, but uses a font not
+ available on older printers).
+
+@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 just like
+ the PCL back-end does.
+
+@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 ", 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, 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, Supported Encodings, The API, Top
+@chapter The @i{barcode} frontend program
+
+%MANPAGE barcode.1
+%M .TH BARCODE 1 "October 2001" "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] [
+%M .I other-flags
+%M ]
+%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::
+@end menu
+
+%--------------------------------------------------------------------------
+@node The Command Line, , 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-length).
+ 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). Unspecified margin values will result in
+ no margin; unspecified size results in default size.
+ The specified values represent print points by
+ default, and can be inches, millimeters or other units
+ according to the @t{-u} option or the @t{BARCODE_UNIT}
+ environment variable. 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. The size (but not the position)
+ of a barcode item within a table can also be selected using
+ @t{-g} (see "geometry" above), without struggling with
+ external and internal margins. I still think management of
+ geometries in a table is suboptimal, but I can't make it
+ better without introducing incompatibilities.
+
+
+@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 as EPS only one barcode is encoded.
+
+@item -P
+ PCL output. Please note that the Y direction goes from top
+ to bottom for PCL, and the origin for an image is the top-left
+ corner instead of the bottom-left
+
+@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, PCL Output, The barcode Executable, Top
+@chapter 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.
+The following list of supported types is sorted in the same order
+the library uses when auto-detecting a suitable encoding for a string.
+
+@table @var
+
+@item EAN
+ The EAN frontend is similar to UPC; it accepts strings of
+ digits, 12 or 7 characters long. Strings of 13 or 8 characters
+ are accepted if the provided checksum digit is correct.
+ I expect most users to feed input without a
+ checksum, though. The add-2 and add-5 extension are accepted for both
+ the EAN-13 and the EAN-8 encodings.
+ The following are example of valid input strings:
+ ``@t{123456789012}'' (EAN-13), ``@t{1234567890128}'' (EAN-13 wih
+ checksum), ``@t{1234567}'' (EAN-8), ``@t{12345670 12345}'' (EAN-8
+ with checksum and add-5),
+ ``@t{123456789012 12}'' (EAN-13 with add-2),
+ ``@t{123456789012 12345}'' (EAN-13 with add-5).
+
+@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 or 12 digits (UPC-A) and 6 or 7 or 8
+ digits (UPC-E).
+
+ The 12th digit of UPC-A is the checksum and is added by the
+ library if not specified in the input; if it is specified, it
+ must be the right checksum or the code is rejected as invalid.
+ For UPC-E, 6 digit are considered to be the middle part of the
+ code, a leading 0 is assumed and the checksum is added;
+ 7 digits are either considered the initial part (leading digit
+ 0 or 1, checksum missing) or the final part (checksum specified,
+ leading 0 assumed); 8 digits are considered to be the complete code,
+ with leading 0 or 1 and checksum.
+ For both UPC-A and UPC-E, a trailing string of 2 digits or 5 digits
+ is accepted as well. Therefore, the following are examples
+ of valid strings that can be encoded as UPC:
+ ``@t{01234567890}'' (UPC-A)
+ ``@t{012345678905}'' (UPC-A with checksum), ``@t{012345}''
+ (UPC-E), ``@t{01234567890 12}'' (UPC-A, add-2) and
+ ``@t{01234567890 12345}'' (UPC-A, add-5), ``@t{0123456 12}''
+ (UPC-E, add-2).
+ Please note that when setting @t{BARCODE_ANY} to auto-detect
+ the encoding to be used, 12-digit strings and 7-digit strings
+ will always be identified as EAN. This because I expect most
+ user to provide input without a checksum. If you need to
+ specify UPC-with-checksum as input you must explicitly set
+ @t{BARCODE_UPC} as a flag or use @t{-e upc} on the command line.
+
+@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}'', ``@t{3-89721-122-X}'' and ``@t{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 128 raw
+ Code-128 output represented symbol-by-symbol in the input
+ string. To override part of the problems outlined below in
+ specifying code128 symbols, this pseudo-encoding allows the
+ used to specify a list of code128 symbols separated by
+ spaces. Each symbol is represented by a number in the range
+ 0-105. The list should include the leading character.The
+ checksum and the stop character are automatically added by the
+ library. Most likely this pseudo-encoding will be used with
+ @t{BARCODE_NO_ASCII} and some external program to supply the
+ printed text.
+
+@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).
+
+@item code 128
+ Automatic selection between alphabet A, B and C of the Code-128
+ standard. This encoding can represent all ASCII symbols, from
+ 0 (NUL) to 127 (DEL), as well as four special symbols, named
+ F1, F2, F3, F4. The set of symbols available in this encoding
+ is not easily represented as input to the @i{barcode} library,
+ so the following convention is used. In the input string,
+ which is a C-language null-terminated string, the NUL char
+ is represented by the value 128 (0x80, 0200) and the F1-F4 characters
+ are represented by the values 193-196 (0xc1-0xc4, 0301-0304).
+ The values have been chosen to ease their representation as
+ escape sequences.
+
+ Since the shell doesn't seem to interpret escape sequences on the
+ command line, the "-b" option cannot be easily used to designate
+ the strings to be encoded. As a workaround you can resort
+ to the command @t{echo}, either within back-ticks or used
+ separately to create a file that is then fed to the standard-input
+ of @i{barcode} -- assuming your @t{echo} command processes escape
+ sequences. The newline character is especially though to encode
+ (but not impossible unless you use a @t{csh} variant.
+
+ These problems only apply to the command-line tool; the use of
+ library functions doesn't give any problem. In needed, you can
+ use the ``@i{code 128 raw}'' pseudo-encoding to represent
+ code128 symbols by their numerical value. This encoding is
+ used late in the auto-selection mechanism because (almost) any
+ input string can be represented using code128.
+
+@item Codabar
+ Codabar can encode the ten digits and a few special symbols
+ (minus, plus, dollar, colon, bar, dot). The characters
+ ``@t{A}'', ``@t{B}'', ``@t{C}'' and ``@t{D}'' are used to
+ represent four different start/stop characters. The input
+ string to the barcode library can include the start and stop
+ characters or not include them (in which case ``@t{A}'' is
+ used as start and ``@t{B}'' as stop). Start and stop
+ characters in the input string can be either all lowercase or
+ all uppercase and are always printed as uppercase.
+
+@item Plessey
+ Plessey barcodes can encode all the hexadecimal
+ digits. Alphabetic digits in the input string must either be
+ all lowercase or all uppercase. The output text is always
+ uppercase.
+
+@item MSI
+ MSI can only encode the decimal digits. While the standard
+ specifies either one or two check digits, the current
+ implementation in this library only generates one check digit.
+
+@item code 93
+ The code-93 standard can natively encode 48 different characters,
+ including uppercase letters, digits, the blank space, plus, minus,
+ dot, star, dollar, slash, percent, as well as five special
+ characters: a start/stop delimiter and four "shift characters" used
+ for extended encoding. Using this "extended encoding" method, any
+ standard 7-bit ASCII character can be encoded, but it takes up two
+ symbol lengths in barcode if the character is not natively supported
+ (one of the 48).
+ The encoder here fully implements the code 93 encoding standard.
+ Any characters natively supported (A-Z, 0-9, ".+-/$&%") will be
+ encoded as such - for any other characters (such as lower case
+ letters, brackets, parentheses, etc.), the encoder will revert
+ to extended encoding.
+ As a note, the option to exclude the checksum will eliminate the
+ two modulo-47 checksums (called C and K) from the barcode, but this
+ probably will make it unreadable by 99% of all scanning systems.
+ These checksums are specified to be used at the firmware level,
+ and their absence will be interpreted as an invalid barcode.
+
+
+@end table
+
+%M .SH PCL OUTPUT
+
+%##########################################################################
+@node PCL Output, Bugs and Pending Issues, Supported Encodings, Top
+@chapter PCL Output
+
+While the default output is Postscript (possibly EPS), and Postscript
+can be post-processed to almost anything, it is sometimes desirable to
+create output directly usable by the specific printer at hand.
+PCL is currently supported as an output format for this reason.
+Please note that the Y coordinate for PCL goes from top to bottom, while
+for Postscript it goes from bottom to top. Consistently, while in
+Postscript you specify the bottom-left corner as origin, for PCL
+you specify the top-left corner.
+
+Barcode output for PCL Printers (HP LaserJet and compatibles),
+was developed using PCL5 Reference manuals from HP.
+that really refers to these printers:
+@itemize @bullet
+
+@item
+LaserJet III, III P, III D, III Si,
+
+@item
+LaserJet 4 family
+
+@item
+LaserJet 5 family
+
+@item
+LaserJet 6 family
+
+@item
+Color LaserJet
+
+@item
+DeskJet 1200 and 1600.
+
+@end itemize
+
+However, barcode printing uses a very small subset of PCL, probably also
+LaserJet II should print it without problem, but the resulting text may
+be horrible.
+
+The only real difference from one printer to another really depends on
+which font are available in the printer, used in printing the label
+associated to the bars (if requested).
+
+Earlier LaserJet supports only bitmaps fonts, so these are not
+"scalable". (Ljet II ?), Also these fonts, when available, have a
+specified direction, and not all of them are available in
+both Portrait and Landscape mode.
+
+From LaserJet 4 series, (except 4L/5L that are entry-level printers),
+Arial scalable font should be available, so it's the "default font"
+used by this program.
+
+LaserJet III series printers (and 4L, 5L), don't feature "Arial" as a
+resident font, so you should use @t{BARCODE_OUT_PCL_III} instead of
+@t{BARCODE_OUT_PCL.}, and font the font used will be "Univers" instead
+of "Arial".
+
+Results on compatible printers, may depend on consistency of
+PCL5 compatibility, in doubt, try BARCODE_OUT_PCL_III
+
+PJL commands are not used here, as it's not very compatible.
+
+
+Tested Printers:
+@itemize @bullet
+@item
+Hp LaserJet 4050
+@item
+Hp LaserJet 2100
+@item
+Epson N-1200 emul PCL
+@item
+Toshiba DP2570 (copier) + PCL option
+@item
+Epson EPL-7100 emul. HP LaserJet II: bars print fine but text is bad.
+@end itemize
+
+
+%M .SH BUGS
+
+%##########################################################################
+@node Bugs and Pending Issues, , PCL Output, Top
+@chapter 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).
+
+EAN-128 is not (yet) supported. I plan to implement it pretty soon and
+then bless the package as version 1.0.
+
+%M .SH "SEE ALSO"
+%M \fBbarcode(3)\fP
+%M
+%M .SH AUTHORS
+%M Alessandro Rubini <rubini@gnu.org> (maintainer)
+%M .PP
+%M Leonid A. Broukhis <leob@mailcom.com> (several encodings)
+%M .PP
+%M Andrea Scopece <a.scopece@tin.it> (PCL output)
+%MANPAGE END
+
+@iftex
+@contents
+@end iftex
+
+@bye
+@c LocalWords: barcode ifinfo titlepage iftex texinfo ascii frontend LGPL
+@c LocalWords: tarball malloced textinfo scalef isbn Plessey codabar GPL Ljet
+@c LocalWords: LocalWords LaserJet Univers Arial Debian libpaper pagesize
+@c LocalWords: Epson MANPAGE stderr barcodes emul DeskJet xmargin ymargin
+@c LocalWords: leftmargin rightmargin topmargin bottommargin unset struct
+@c LocalWords: NOHEADERS yoff xoff versionname errno malloc behaviour charset
projects / glabels / blobdiff