\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 %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{} @t{x} @i{}] [@t{+} @i{} @t{+} @i{}]'' (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{} @t{x} @i{} [@t{+} @i{} @t{+} @i{} [@t{-} @i{} [@t{-} @i{}]]]'' (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{}@t{,}@i{}'' 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 (maintainer) %M .PP %M Leonid A. Broukhis (several encodings) %M .PP %M Andrea Scopece (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