File: barcode.texi

package info (click to toggle)
barcode 0.99-3
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 4,648 kB
  • sloc: ansic: 21,507; sh: 11,815; makefile: 24; sed: 16
file content (959 lines) | stat: -rw-r--r-- 37,860 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
n\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".
%
%------------------------------------------------------------------------------


@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. Therefore, version
	1.03.5 will be returned as 1035 and version 0.53 as 53.  If
        the argument is non-null, it will be used to return the version
        number as a string.
@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. The margins can be negative values. This
        can be useful with the option -s for fine tuning the placement of the
        barcode.

@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).
	
@item -s
	The streaming mode. In this mode, available only for PCL output
	and not for table output, the PCL output can be printed within
	other PCL data. The barcode will be printed aligned with previously
	printed text. After printing the barcode, the position of the cursor
	is still the same vertically (y) but it has advanced by the width of
	the barcode plus the x margin. The exact position of the barcode
	can be fine tuned with option @t{-g}, @t{xmargin} and @t{ymargin}. In
        streaming mode, no PCL code is generated that would change the charset
	encoding and the font. This is expected to be done by the surrounding
	PCL code generated by a printing application.

	Use case: A legacy application might generate output like
	@t{Articlename: EAN13START -b761005201696 -g30x10 EAN13END}.
	It is easy to write a filter which replaces @t{EAN13START...EAN13END}
	by the correct PCL code using @t{barcode -s}. Add that filter to the
	printer spooling system, and your ancient application can print
	barcodes without having to add barcode printing code to it. You
	can find an example of such a filter in the @t{doc} subdirectory of the
	barcode distribution, in the file @t{pclfilter.py}.

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

@item code 11
     The code-11 standard (also known as USD-8) is able to encode the 
     decimal digits and the dash symbol (-).
     It is used primarily in labeling telecommunications equipment.
     As recommended by the standard the current implementation adds 
     by default a checksum digit. An additional checksum digit is added 
     for messages that contain 10 or more characters.

@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 fonts 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 on (except 4L/5L which are entry-level printers),
the "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 the font used will be "Univers" instead
of "Arial".

Results on compatible printers may depend on consistency of
PCL5 compatibility. In doubt try @t{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