1 \input texinfo @c -*-texinfo-*-
3 % doc.barcode - main file for the documentation
7 %------------------------------------------------------------------------------
9 % NOTE FOR THE UNAWARE USER
10 % =========================
12 % This file is a texinfo source. It isn't the binary file of some strange
13 % editor of mine. If you want ascii, you should "make barcodedoc.txt".
15 %------------------------------------------------------------------------------
18 % This is not a conventional info file...
19 % I use two extra features:
20 % - The '%' as a comment marker, if at beg. of line ("\%" -> "%")
21 % - leading blanks are allowed
24 @comment %**start of header
25 @setfilename barcode.info
26 @settitle Barcode @value{version}
30 @comment %**end of header
32 @setchapternewpage off
35 @set update-month March 2002
41 This file is the User's Manual for the barcode library (version
46 @setchapternewpage odd
48 @c use the new format for titles
49 @title barcode @value{version}
50 @subtitle A library for drawing bar codes
51 @subtitle @value{update-month}
53 @author by Alessandro Rubini (@code{rubini@@gnu.org})
56 @setchapternewpage off
60 @node Top, Overview, (dir), (dir)
63 This file documents version @value{version} of the barcode
64 library and sample programs (@value{update-month}).
68 * The Barcode Object::
71 * The barcode Executable::
72 * Supported Encodings::
74 * Bugs and Pending Issues::
78 %##########################################################################
79 %##########################################################################
81 @node Overview, The Barcode Object, Top, Top
84 The @dfn{barcode} package is mainly a C library for creating bar-code
85 output files. It also includes a command line front-end and (in a
86 foreseeable future) a graphic frontend.
88 The package is designed as a library because we think the main use for
89 barcode-generation tools is inside more featured applications. The
90 library addresses bar code printing as two distinct problems: creation
91 of bar information and actual conversion to an output format. To this
92 aim we use an intermediate representation for bar codes, which is
93 currently documented in the @file{ps.c} source file (not in this
96 Note that the library and the accompanying material is released
97 according to the GPL license, not the LGPL one. A copy of the GPL is
98 included in the distribution tarball.
100 %##########################################################################
102 @node The Barcode Object, Supported Flags, Overview, Top
103 @chapter The Underlying Data Structure
105 Every barcode-related function acts on a data structure defined in the
106 @file{barcode.h} header, which must be included by any C source file
107 that uses the library. The header is installed by @t{make install}.
109 The definition of the data structure is included here for reference:
112 struct Barcode_Item @{
113 int flags; /* type of encoding and other flags */
114 char *ascii; /* malloced */
115 char *partial; /* malloced too */
116 char *textinfo; /* information about text placement */
117 char *encoding; /* code name, filled by encoding engine */
118 int width, height; /* output units */
119 int xoff, yoff; /* output units */
120 int margin; /* output units */
121 double scalef; /* requested scaling for barcode */
122 int error; /* an errno-like value, in case of failure */
126 The exact meaning of each field and the various flags implemented are
127 described in the following sections.
129 Even though you won't usually need to act on the contents of this
130 structure, some of the functions in the library receive arguments that
131 are directly related to one or more of these fields.
133 %==========================================================================
137 * The Intermediate Representation::
140 %--------------------------------------------------------------------------
141 @node The Field List, The Intermediate Representation, The Barcode Object, The Barcode Object
148 The flags are, as you may suspect, meant to specify the exact
149 behaviour of the library. They are often passed as an argument
150 to @i{barcode} functions and are discussed in the next section.
153 @itemx char *partial;
154 @itemx char *textinfo;
155 @itemx char *encoding;
157 These fields are internally managed by the library, and you are
158 not expected to touch them if you use the provided API. All
159 of them are allocated with @i{malloc}.
164 They specify the width and height of the @i{active} barcode
165 region (i.e., excluding the white margin), in the units used
166 to create output data (for postscript they are points, 1/72th
167 of an inch, 0.352 mm). The fields can be either assigned to
168 in the structure or via @i{Barcode_Position()}, at your
169 choice. If either value or both are left to their default
170 value of zero, the output engine will assign default values
171 according to the specified scaling factor. If the specified
172 width is bigger than needed (according to the scaling factor),
173 the output barcode will be centered in its requested
174 region. If either the width of the height are too small for
175 the specified scale factor, the output bar code will expand
176 symmetrically around the requested region.
181 The fields specify offset from the coordinate origin of the
182 output engine (for postscript, position 0,0 is the lower left
183 corner of the page). The fields can be either assigned to in
184 the structure or via @i{Barcode_Position()}, at your choice.
185 The offset specifies where the white margin begins, not where
186 the first bar will be printed. To print real ink to the
187 specified position you should set @i{margin} to 0.
191 The white margin that will be left around the printed area of
192 the bar code. The same margin is applied to all sides of the
193 printed area. The default value for the margin is defined in
194 @file{barcode.h} as @t{BARCODE_DEFAULT_MARGIN} (10).
198 The enlarge or shrink value for the bar code over its default
199 dimension. The @i{width} and @i{scalef} fields interact deeply
200 in the creation of the output, and a complete description of
201 the issues appears later in this section.
205 The field is used when a @i{barcode} function fails to host
206 an @t{errno}-like integer value.
211 @unnumberedsubsec Use of the @i{width} and @i{scalef} fields.
213 A width unit is the width of the thinnest bar and/or space in the
214 chosen code; it defaults to 1 point if the output is postscript or
215 encapsulated postscript.
217 Either or both the code width and the scale factor can be left
218 unspecified (i.e., zero). The library deals with defaults in the
223 @item Both unspecified
225 If both the width and the scale factor are unspecified, the
226 scale factor will default to 1.0 and the width is calculated
227 according to the actual width of the bar code being printed.
229 @item Width unspecified
231 If the width is not specified, it is calculated according to
232 the values of @i{scalef}.
234 @item Scale factor unspecified
236 If the scale factor is not specified, it will be chosen so
237 that the generated bar code exactly fits the specified width.
241 The code will be printed inside the specified region according
242 to the specified scale factor. It will be aligned to the left.
243 If, however, the chosen width is too small for the specific
244 bar code and scaling factor, then the code will extend
245 symmetrically to the left and to the right of the chosen
250 %--------------------------------------------------------------------------
251 @node The Intermediate Representation, , The Field List, The Barcode Object
252 @section The Intermediate Representation
254 The encoding functions print their output into the @t{partial} and
255 @t{texinfo} fields of the barcode data structure. Those fields, together
256 with position information, are then used to generate actual output.
257 This is an informal description of the intermediate format.
259 The first char in @t{partial} tells how much extra space to add to the
260 left of the bars. For EAN-13, it is used to leave space to print the
261 first digit, other codes may have '0' for no-extra-space-needed.
263 The next characters are alternating bars and spaces, as multiples of the
264 base dimension which is 1 unless the code is rescaled. Rescaling is
265 calculated as the ratio from the requested width and the calculated
266 width. Digits represent bar/space dimensions. Lower-case letters
267 represent those bars that should extend lower than the others: 'a' is
268 equivalent to '1', 'b' is '2' and so on up to 'i' which is equivalent to
269 '9'. Other letters will be used for encoding-specific meanings, as soon
272 The @t{textinfo} string is made up of fields @t{%lf:%lf:%c} separated by
273 blank space. The first integer is the x position of the character,
274 the second is the font size (before rescaling) and the char item is
275 the character to be printed.
277 Both the @t{partial} and @t{textinfo} strings may include ``@t{-}'' or
278 ``@t{+}'' as special characters (in @t{textinfo} the char should be a
279 stand-alone word). They state where the text should be printed: below
280 the bars (``@t{-}'', default) or above the bars. This is used, for
281 example, to print the add-5 and add-2 codes to the right of UPC or EAN
282 codes (the add-5 extension is mostly used in ISBN codes).
287 %==========================================================================
289 @node Supported Flags, The API, The Barcode Object, Top
292 The following flags are supported by version @value{version} of the
297 @item BARCODE_ENCODING_MASK
299 The mask is used to extract the encoding-type identifier from
308 @itemx BARCODE_128RAW
316 The currently supported encoding types: EAN (13 digits, 8
317 digits, 13 + 2 add-on and 13 + 5 add-on), UPC (UPC-A, UPC-E,
318 UPC-A with 2 or 5 digit add-on), ISBN (with or without the
319 5-digit add-on), CODE128-B (the whole set of printable
320 ASCII characters), CODE128-C (two digits encoded by each barcode
321 symbol), CODE128 (all ASCII values), a ``raw-input'' pseudo-code
322 that generates CODE128 output, CODE39 (alphanumeric),
323 "interleaved 2 of 5" (numeric), Codabar (numeric plus a few
324 symbols), MSI (numeric) and Plessey (hex digits).
325 @xref{Supported Encodings}.
329 This special encoding type (represented by a value of zero, so
330 it will be the default) tells the encoding procedure to look
331 for the first encoding type that can deal with a textual
332 string. Therefore, a 11-digit code will be printed as UPC (as
333 well as 6-digit, 11+2 and 11+5), a 12-digit (or 7-digit, or
334 12+2 or 12+5) as EAN13, an ISBN code (with or without hyphens,
335 with or without add-5) will be encoded in its EAN13
336 representation, an even number of digits is encoded using
337 CODE128C and a generic string is encoded using CODE128B. Since
338 code-39 offers a much larger representation for the same
339 text string, code128-b is preferred over code39 for
340 alphanumeric strings.
342 @item BARCODE_NO_ASCII
344 Instructs the engine not to print the ascii string on
345 output. By default the bar code is accompanied with an ascii
346 version of the text it encodes.
348 @item BARCODE_NO_CHECKSUM
350 Instructs the engine not to add the checksum character to the
351 output. Not all the encoding types can drop the checksum;
352 those where the checksum is mandatory (like EAN and UPC)
353 just ignore the flag.
355 @item BARCODE_OUTPUT_MASK
357 The mask is used to extract the output-type identifier from
361 @itemx BARCODE_OUT_EPS
362 @itemx BARCODE_OUT_PCL
363 @itemx BARCODE_OUT_PCL_III
365 The currently supported encoding types: full-page postscript
366 and encapsulated postscript; PCL (print command language, for
367 HP printers) and PCL-III (same as PCL, but uses a font not
368 available on older printers).
370 @item BARCODE_OUT_NOHEADERS
372 The flag instructs the printing engine not to print the header
373 and footer part of the file. This makes sense for the
374 postscript engine but might not make sense for other engines;
375 such other engines will silently ignore the flag just like
376 the PCL back-end does.
380 %##########################################################################
382 @node The API, The barcode Executable, Supported Flags, Top
383 @chapter Functions Exported by the Library
386 %M .TH BARCODE 3 "October 1999" "GNU" "GNU barcode"
389 %M barcode \- a library to create and print bar codes
391 %M .B #include <barcode.h>
393 %M .BI "struct Barcode_Item *Barcode_Create(char *" text ");"
395 %M .BI "int Barcode_Delete(struct Barcode_Item *" bc ");"
397 %M .BI "int Barcode_Encode(struct Barcode_Item *" bc ", int " flags ");"
399 %M .BI "int Barcode_Print(struct Barcode_Item *" bc ", FILE *" f ", int " flags ");"
401 %M .BI "int Barcode_Position(struct Barcode_Item *" bc ", int " wid ", int " hei ", int " xoff ", int " yoff " , double " scalef ");"
403 %M .BI "int Barcode_Encode_and_Print(char *" text ", FILE *" f ", int " wid ", int " hei ", int " xoff ", int " yoff ", int " flags ");"
405 %M .BI "int Barcode_Version(char *" versionname ");"
409 %M The barcode family of library functions is meant to ease
410 %M creation of bar-code printouts.
412 %M The information below is extracted from the texinfo file, which is the
413 %M preferred source of information.
415 The functions included in the barcode library are declared in the
416 header file @t{barcode.h}. They perform the following tasks:
420 @item struct Barcode_Item *Barcode_Create(char *text);
421 The function creates a new barcode object to deal with a
422 specified text string. It returns NULL in case of failure and
423 a pointer to a barcode data structure in case of success.
425 @item int Barcode_Delete(struct Barcode_Item *bc);
426 Destroy a barcode object. Always returns 0 (success)
428 @item int Barcode_Encode(struct Barcode_Item *bc, int flags);
429 Encode the text included in the @i{bc} object. Valid flags are
430 the encoding type (other flags are ignored) and
431 BARCODE_NO_CHECKSUM (other flags are silently ignored); if the
432 flag argument is zero, @t{bc->flags} will apply. The function
433 returns 0 on success and -1 in case of error. After
434 successful termination the data structure will host the
435 description of the bar code and its textual representation,
436 after a failure the @t{error} field will include the reason of
439 @item int Barcode_Print(struct Barcode_Item *bc, FILE *f, int flags);
440 Print the bar code described by @t{bc} to the specified file.
441 Valid flags are the output type, @t{BARCODE_NO_ASCII} and
442 @t{BARCODE_OUT_NOHEADERS}, other flags are ignored. If any of
443 these flags is zero, it will be inherited from @t{bc->flags}
444 which therefore takes precedence. The function returns 0 on
445 success and -1 in case of error (with @t{bc->error} set
446 accordingly). In case of success, the bar code is printed to
447 the specified file, which won't be closed after use.
449 @item int Barcode_Position(struct Barcode_Item *bc, int wid, int hei, int xoff, int yoff, double scalef);
450 The function is a shortcut to assign values to the data
453 @item int Barcode_Encode_and_Print(char *text, FILE *f, int wid, int hei, int xoff, int yoff, int flags);
454 The function deals with the whole life of the barcode
455 object by calling the other functions; it uses all the specified
458 @item int Barcode_Version(char *versionname);
459 Returns the current version as an integer number of the form
460 major * 10000 + minor * 100 + release. Therefore, version
461 1.03.5 will be returned as 10305 and version 0.53 as 5300. If
462 the argument is non-null, it will be used to return the version
463 number as a string. Note that the same information is available from
464 two preprocessor macros: @t{BARCODE_VERSION} (the string) and
465 @t{BARCODE_VERSION_INT} (the integer number).
471 %##########################################################################
473 @node The barcode Executable, Supported Encodings, The API, Top
474 @chapter The @i{barcode} frontend program
477 %M .TH BARCODE 1 "October 2001" "GNU" "GNU barcode"
480 %M barcode \- a stand alone program to run the barcode library
483 %M [\-b - | string] [\-e encoding] [\-o - | outfile] [
488 %M The information below is extracted from the texinfo file, which is the
489 %M preferred source of information.
491 The @b{barcode} program is a front-end to access some features of the
492 library from the command line. It is able to read user supplied
493 strings from the command line or a data file (standard input by default)
494 and encode all of them.
503 %--------------------------------------------------------------------------
504 @node The Command Line, , The barcode Executable, The barcode Executable
505 @section The Command Line
508 @b{barcode} accepts the following options:
513 Print a usage summary and exit.
516 Identify a file where strings to be encoded are read from. If
517 missing (and if @t{-b} is not used) it defaults to standard
518 input. Each data line of the input file will be used to create
522 Output file. It defaults to standard output.
525 Specify a single ``barcode'' string to be encoded.
526 The option can be used multiple times in order to encode
527 multiple strings (this will result in multi-page postscript
528 output or a table of barcodes if @t{-t} is specified). The
529 strings must match the encoding chosen; if it doesn't
530 match the program will print a warning to @t{stderr} and
531 generate ``blank'' output (although not zero-length).
532 Please note that a string including spaces or
533 other special characters must be properly quoted.
536 @b{encoding} is the name of the chosen encoding format being
537 used. It defaults to the value of the environment variable
538 @t{BARCODE_ENCODING} or to auto detection if the environment is
542 The geometry argument is of the form ``[@i{<width>} @t{x}
543 @i{<height>}] [@t{+} @i{<xmargin>} @t{+} @i{<ymargin>}]'' (with
544 no intervening spaces). Unspecified margin values will result in
545 no margin; unspecified size results in default size.
546 The specified values represent print points by
547 default, and can be inches, millimeters or other units
548 according to the @t{-u} option or the @t{BARCODE_UNIT}
549 environment variable. The argument is used to place the
550 printout code on the page. Note that an additional white
551 margin of 10 points is added to the printout. If the option is
552 unspecified, @t{BARCODE_GEOMETRY} is looked up in the
553 environment, if missing a default size and no margin (but the
554 default 10 points) are used.
556 @item -t table-geometry
557 Used to print several barcodes to a single page, this option
558 is meant to be used to print stickers. The argument is of the
559 form ``@i{<columns>} @t{x} @i{<lines>} [@t{+} @i{<leftmargin>}
560 @t{+} @i{<bottommargin>} [@t{-} @i{<rightmargin>} [@t{-}
561 @i{<topmargin>}]]]'' (with no intervening spaces); if missing,
562 the top and right margin will default to be the same as the
563 bottom and left margin. The margins are specified in print
564 points or in the chosen unit (see @t{-u} below). If the
565 option is not specified, @t{BARCODE_TABLE} is looked up in the
566 environment, otherwise no table is printed and each barcode
567 will get its own page. The size (but not the position)
568 of a barcode item within a table can also be selected using
569 @t{-g} (see "geometry" above), without struggling with
570 external and internal margins. I still think management of
571 geometries in a table is suboptimal, but I can't make it
572 better without introducing incompatibilities.
576 Specifies an internal margin for each sticker in the
577 table. The argument is of the form
578 ``@i{<xmargin>}@t{,}@i{<ymargin>}'' and the margin is applied
579 symmetrically to the sticker. If unspecified, the environment
580 variable @t{BARCODE_MARGIN} is used or a default internal
581 margin of 10 points is used.
584 ``Numeric'' output: don't print the ASCII form of the code,
588 No checksum character (for encodings that allow it, like code 39,
589 other codes, like UPC or EAN, ignore this option).
592 Encapsulated postscript (default is normal postscript). When
593 the output is generated as EPS only one barcode is encoded.
596 PCL output. Please note that the Y direction goes from top
597 to bottom for PCL, and the origin for an image is the top-left
598 corner instead of the bottom-left
601 Specify a non-default page size. The page size can be specified
602 in millimeters, inches or plain numbers (for example: "@t{210x297mm}",
603 "@t{8.5x11in}", "@t{595x842}"). A page specification as numbers
604 will be interpreted according to the current unit specification
605 (see @t{-u} below). If libpaper is available,
606 you can also specify the page size with its name, like "@t{A3}"
607 or "@t{letter}" (libpaper is a standard component of Debian
608 GNU/Linux, but may be missing elsewhere). The default page
609 size is your system-wide default if libpaper is there, A4 otherwise.
612 Choose the unit used in size specifications. Accepted values
613 are ``mm'', ``cm'', ``in'' and ``pt''. By default, the program
614 will check @t{BARCODE_UNIT} in the environment, and assume
615 points otherwise (this behaviour is compatible with 0.92 and
616 previous versions. If @t{-u} appears more than once, each
617 instance will modified the behaviour for the arguments at its
618 right, as the command line is processes left to right. The
619 program internally works with points, and any size is
620 approximated to the nearest multiple of one point. The @t{-u}
621 option affect @t{-g} (geometry), @t{-t} (table) and @t{-p}
626 %M .SH ENCODING TYPES
629 %##########################################################################
630 @node Supported Encodings, PCL Output, The barcode Executable, Top
631 @chapter Supported Encodings
633 The program encodes text strings passed either on the command line
634 (with -b) or retrieved from standard input. The text representation is
635 interpreted according to the following rules. When auto-detection
636 of the encoding is enabled (i.e, no explicit encoding type is specified),
637 the encoding types are scanned to find one that can digest the text string.
638 The following list of supported types is sorted in the same order
639 the library uses when auto-detecting a suitable encoding for a string.
644 The EAN frontend is similar to UPC; it accepts strings of
645 digits, 12 or 7 characters long. Strings of 13 or 8 characters
646 are accepted if the provided checksum digit is correct.
647 I expect most users to feed input without a
648 checksum, though. The add-2 and add-5 extension are accepted for both
649 the EAN-13 and the EAN-8 encodings.
650 The following are example of valid input strings:
651 ``@t{123456789012}'' (EAN-13), ``@t{1234567890128}'' (EAN-13 wih
652 checksum), ``@t{1234567}'' (EAN-8), ``@t{12345670 12345}'' (EAN-8
653 with checksum and add-5),
654 ``@t{123456789012 12}'' (EAN-13 with add-2),
655 ``@t{123456789012 12345}'' (EAN-13 with add-5).
658 The UPC frontend accepts only strings made up of digits (and,
659 if a supplemental encoding is used, a blank to separate it).
660 It accepts strings of 11 or 12 digits (UPC-A) and 6 or 7 or 8
663 The 12th digit of UPC-A is the checksum and is added by the
664 library if not specified in the input; if it is specified, it
665 must be the right checksum or the code is rejected as invalid.
666 For UPC-E, 6 digit are considered to be the middle part of the
667 code, a leading 0 is assumed and the checksum is added;
668 7 digits are either considered the initial part (leading digit
669 0 or 1, checksum missing) or the final part (checksum specified,
670 leading 0 assumed); 8 digits are considered to be the complete code,
671 with leading 0 or 1 and checksum.
672 For both UPC-A and UPC-E, a trailing string of 2 digits or 5 digits
673 is accepted as well. Therefore, the following are examples
674 of valid strings that can be encoded as UPC:
675 ``@t{01234567890}'' (UPC-A)
676 ``@t{012345678905}'' (UPC-A with checksum), ``@t{012345}''
677 (UPC-E), ``@t{01234567890 12}'' (UPC-A, add-2) and
678 ``@t{01234567890 12345}'' (UPC-A, add-5), ``@t{0123456 12}''
680 Please note that when setting @t{BARCODE_ANY} to auto-detect
681 the encoding to be used, 12-digit strings and 7-digit strings
682 will always be identified as EAN. This because I expect most
683 user to provide input without a checksum. If you need to
684 specify UPC-with-checksum as input you must explicitly set
685 @t{BARCODE_UPC} as a flag or use @t{-e upc} on the command line.
688 ISBN numbers are encoded as EAN-13 symbols, with an optional
689 add-5 trailer. The ISBN frontend of the library accepts real
690 ISBN numbers and deals with any hyphen and, if present, the
691 ISBN checksum character before encoding data. Valid
692 representations for ISBN strings are for example:
693 ``@t{1-56592-292-1}'', ``@t{3-89721-122-X}'' and ``@t{3-89721-122-X
697 This encoding can represent all of the printing ASCII
698 characters, from the space (32) to DEL (127). The checksum
699 digit is mandatory in this encoding.
702 The ``C'' variation of Code-128 uses Code-128 symbols to
703 represent two digits at a time (Code-128 is made up of 104
704 symbols whose interpretation is controlled by the start symbol
705 being used). Code 128-C is thus the most compact way to
706 represent any even number of digits. The encoder refuses to
707 deal with an odd number of digits because the caller is
708 expected to provide proper padding to an even number of
709 digits. (Since Code-128 includes control symbols to switch
710 charset, it is theoretically possible to represent the odd
711 digit as a Code 128-A or 128-B symbol, but this tool doesn't
712 currently implement this option).
715 Code-128 output represented symbol-by-symbol in the input
716 string. To override part of the problems outlined below in
717 specifying code128 symbols, this pseudo-encoding allows the
718 used to specify a list of code128 symbols separated by
719 spaces. Each symbol is represented by a number in the range
720 0-105. The list should include the leading character.The
721 checksum and the stop character are automatically added by the
722 library. Most likely this pseudo-encoding will be used with
723 @t{BARCODE_NO_ASCII} and some external program to supply the
727 The code-39 standard can encode uppercase letters, digits, the
728 blank space, plus, minus, dot, star, dollar, slash, percent.
729 Any string that is only composed of such characters is
730 accepted by the code-39 encoder. To avoid loosing information,
731 the encoder refuses to encode mixed-case strings (a lowercase
732 string is nonetheless accepted as a shortcut, but is encoded
735 @item interleaved 2 of 5
736 This encoding can only represent an even number of digits
737 (odd digits are represented by bars, and even digits by the
738 interleaving spaces). The name stresses the fact that two
739 of the five items (bars or spaces) allocated to each symbol
740 are wide, while the rest are narrow. The checksum digit is
741 optional (can be disabled via @t{BARCODE_NO_CHECKSUM}).
742 Since the number of digits, including the checksum, must be even,
743 a leading zero is inserted in the string being encoded if needed
744 (this is specifically stated in the specs I have access to).
747 Automatic selection between alphabet A, B and C of the Code-128
748 standard. This encoding can represent all ASCII symbols, from
749 0 (NUL) to 127 (DEL), as well as four special symbols, named
750 F1, F2, F3, F4. The set of symbols available in this encoding
751 is not easily represented as input to the @i{barcode} library,
752 so the following convention is used. In the input string,
753 which is a C-language null-terminated string, the NUL char
754 is represented by the value 128 (0x80, 0200) and the F1-F4 characters
755 are represented by the values 193-196 (0xc1-0xc4, 0301-0304).
756 The values have been chosen to ease their representation as
759 Since the shell doesn't seem to interpret escape sequences on the
760 command line, the "-b" option cannot be easily used to designate
761 the strings to be encoded. As a workaround you can resort
762 to the command @t{echo}, either within back-ticks or used
763 separately to create a file that is then fed to the standard-input
764 of @i{barcode} -- assuming your @t{echo} command processes escape
765 sequences. The newline character is especially though to encode
766 (but not impossible unless you use a @t{csh} variant.
768 These problems only apply to the command-line tool; the use of
769 library functions doesn't give any problem. In needed, you can
770 use the ``@i{code 128 raw}'' pseudo-encoding to represent
771 code128 symbols by their numerical value. This encoding is
772 used late in the auto-selection mechanism because (almost) any
773 input string can be represented using code128.
776 Codabar can encode the ten digits and a few special symbols
777 (minus, plus, dollar, colon, bar, dot). The characters
778 ``@t{A}'', ``@t{B}'', ``@t{C}'' and ``@t{D}'' are used to
779 represent four different start/stop characters. The input
780 string to the barcode library can include the start and stop
781 characters or not include them (in which case ``@t{A}'' is
782 used as start and ``@t{B}'' as stop). Start and stop
783 characters in the input string can be either all lowercase or
784 all uppercase and are always printed as uppercase.
787 Plessey barcodes can encode all the hexadecimal
788 digits. Alphabetic digits in the input string must either be
789 all lowercase or all uppercase. The output text is always
793 MSI can only encode the decimal digits. While the standard
794 specifies either one or two check digits, the current
795 implementation in this library only generates one check digit.
798 The code-93 standard can natively encode 48 different characters,
799 including uppercase letters, digits, the blank space, plus, minus,
800 dot, star, dollar, slash, percent, as well as five special
801 characters: a start/stop delimiter and four "shift characters" used
802 for extended encoding. Using this "extended encoding" method, any
803 standard 7-bit ASCII character can be encoded, but it takes up two
804 symbol lengths in barcode if the character is not natively supported
806 The encoder here fully implements the code 93 encoding standard.
807 Any characters natively supported (A-Z, 0-9, ".+-/$&%") will be
808 encoded as such - for any other characters (such as lower case
809 letters, brackets, parentheses, etc.), the encoder will revert
810 to extended encoding.
811 As a note, the option to exclude the checksum will eliminate the
812 two modulo-47 checksums (called C and K) from the barcode, but this
813 probably will make it unreadable by 99% of all scanning systems.
814 These checksums are specified to be used at the firmware level,
815 and their absence will be interpreted as an invalid barcode.
822 %##########################################################################
823 @node PCL Output, Bugs and Pending Issues, Supported Encodings, Top
826 While the default output is Postscript (possibly EPS), and Postscript
827 can be post-processed to almost anything, it is sometimes desirable to
828 create output directly usable by the specific printer at hand.
829 PCL is currently supported as an output format for this reason.
830 Please note that the Y coordinate for PCL goes from top to bottom, while
831 for Postscript it goes from bottom to top. Consistently, while in
832 Postscript you specify the bottom-left corner as origin, for PCL
833 you specify the top-left corner.
835 Barcode output for PCL Printers (HP LaserJet and compatibles),
836 was developed using PCL5 Reference manuals from HP.
837 that really refers to these printers:
841 LaserJet III, III P, III D, III Si,
856 DeskJet 1200 and 1600.
860 However, barcode printing uses a very small subset of PCL, probably also
861 LaserJet II should print it without problem, but the resulting text may
864 The only real difference from one printer to another really depends on
865 which font are available in the printer, used in printing the label
866 associated to the bars (if requested).
868 Earlier LaserJet supports only bitmaps fonts, so these are not
869 "scalable". (Ljet II ?), Also these fonts, when available, have a
870 specified direction, and not all of them are available in
871 both Portrait and Landscape mode.
873 From LaserJet 4 series, (except 4L/5L that are entry-level printers),
874 Arial scalable font should be available, so it's the "default font"
875 used by this program.
877 LaserJet III series printers (and 4L, 5L), don't feature "Arial" as a
878 resident font, so you should use @t{BARCODE_OUT_PCL_III} instead of
879 @t{BARCODE_OUT_PCL.}, and font the font used will be "Univers" instead
882 Results on compatible printers, may depend on consistency of
883 PCL5 compatibility, in doubt, try BARCODE_OUT_PCL_III
885 PJL commands are not used here, as it's not very compatible.
895 Epson N-1200 emul PCL
897 Toshiba DP2570 (copier) + PCL option
899 Epson EPL-7100 emul. HP LaserJet II: bars print fine but text is bad.
905 %##########################################################################
906 @node Bugs and Pending Issues, , PCL Output, Top
907 @chapter Bugs and Pending Issues.
909 The current management of borders/margins is far from optimal. The
910 ``default'' margin applied by the library interferes with the external
911 representation, but I feel it is mandatory to avoid creating barcode
912 output with no surrounding white space (the problem is especially
913 relevant for EPS output).
915 EAN-128 is not (yet) supported. I plan to implement it pretty soon and
916 then bless the package as version 1.0.
922 %M Alessandro Rubini <rubini@gnu.org> (maintainer)
924 %M Leonid A. Broukhis <leob@mailcom.com> (several encodings)
926 %M Andrea Scopece <a.scopece@tin.it> (PCL output)
934 @c LocalWords: barcode ifinfo titlepage iftex texinfo ascii frontend LGPL
935 @c LocalWords: tarball malloced textinfo scalef isbn Plessey codabar GPL Ljet
936 @c LocalWords: LocalWords LaserJet Univers Arial Debian libpaper pagesize
937 @c LocalWords: Epson MANPAGE stderr barcodes emul DeskJet xmargin ymargin
938 @c LocalWords: leftmargin rightmargin topmargin bottommargin unset struct
939 @c LocalWords: NOHEADERS yoff xoff versionname errno malloc behaviour charset