The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

labels - print labels and envelopes

SYNOPSIS

labels [options] [file ...]

DESCRIPTION

labels will read the given input file(s) and produce a PostScript file that can be used to print text labels.

The input is considered to contain the text lines that must be printed on the labels. One or more empty lines separate entries.

Example:

    labels -paper a4 -rows 7 -cols 3 -left 10 -vcenter \
             -start 5 -repeat 3 < file > file.ps

This defines the paper size to be A4 (210 x 297 mm). Each sheet has 21 labels, arranged in 7 rows of 3 columns. The text on the labels will start 10 mm from the left edge of the label, and is vertically centered. The first entry printed will occupy label number 5 (top-left label is 1, bottom-right label is 21). Each entry is repeated 3 times.

The layout specification can come from the command line, or (much easier) from a configuration file. For this example, the configuration entry would be:

    type 21
    paper a4
    cols 3
    rows 7
    left 10
    vcenter

The command then only needs to select the desired type, start and repetition:

    labels -type 21 -start 5 -repeat 3 < file > file.ps

See below for more details.

COMMAND LINE OPTIONS

This section describes the command line options that do not have a counterpart in the configuration file.

-config file

Designates the name of the configuration file to be used.

-layout

Includes a layout drawing in the PostScript file to illustrate how the printout will look like.

-type XX

Select the layout specification labeled XX from the configuration file.

-start NN

Printing will start at label location NN. This makes it possible to print some labels, peel them off, and continue printing on the same sheet some time later. First label has number 1 (top-left). The last label is the bottom-right one. Default is to start at label 1.

-repeat NN

Repeat every entry NN times. Default is once.

-interline NN

Distance between the baselines of the printed text, in PostScript points. Default is 14 points. Deprecated.

-[no]kix

Enable / disable processing of dutch KIX codes. This is enabled by default.

-output file

Send output to file instead of standard output.

-manual

Print using manual feed.

-help

Print a brief help message and exits.

-ident

Prints program identification.

-verbose

More verbose information.

CONFIGURATION

The program looks for a configuration file in one of the following places:

    .labels.cfg
    $HOME/.labels.cfg
    /usr/local/lib/labels.cfg

The first non-empty file found will be used. A configuration file is optional, unless the -type command line option was used.

Lines starting with # in the configuration file will be ignored. Leading and trailing whitespace is ignored as well.

The configuration file can contain the following definitions:

  • The fonts to use. All fonts can be set in one command:

    fonts plainfont italicfont boldfont bolditalicfont

    Alternatively, individual fonts can be set with one of the commands plainfont, italicfont, boldfont and bolditalicfont, each followed by the name of the font. For example:

        boldfont Palatino-Bold

    The default fonts are Times-Roman, Times-Italic, Times-Bold and Times-BoldItalic.

  • Paper sizes. The format is name width height (dimensions in millimeters). For example:

        paper a4 210 297

    The name of the paper size must be a recognized PostScript paper size, unless it starts with an _ character. In this case, the page dimensions will be registered in the PostScript output.

    Paper sizes `a4' (European A4) and `letter' (US Letter) are predefined.

  • The default layout specification to use, e.g.

        default 21

    This will always select the specification labeled 21 unless overridden with a -type command line option.

  • A layout specification.

All specifications can also be given as command line arguments. However, the values in the configuration file override the command line arguments.

type name

This identifies the following specification with the given name.

Phisical layout specifications.

paper size

The paper size for this entry. Default value is `a4'.

orientation

This can be portrait, landscape, upsidedown and seascape. Default orientation is `portrait'.

Note that rows, columns and margins are all relative to the selected page orientation.

rows NN

The number of rows of labels on a sheet. Default is 1 row.

cols NN

The number of columns on a sheet. Default is 1 column.

The dimensions of the labels are calculated from the paper size and the number of rows and columns. For example, with A4 paper and 7 rows of 3 columns, each label is 70 mm wide and 42.4 mm high.

topmargin NN

Optional margin on the top of each sheet. For sheets that are not completely composed of labels.

bottommargin NN

Optional margin on the bottom of each sheet.

keftmargin NN

Optional margin on the left of each sheet.

rightmargin NN

Optional margin on the right of each sheet.

Placement of the text on the labels.

left NN

The offset, in millimeters, of the printed text from the left edge of each label. Default value is zero, which is not what you want.

top NN

The offset, in millimeters, of the baseline of the first line of printed text from the top edge of each label. Default value is zero, which is probably not what you want unless vcenter is also included in this specification.

vcenter

The lines of text on the label are vertically centered. If top was specified, the remaining vertical space is used for centering.

Centering is nice for labels, but usually not desired for envelopes.

Non-standard page sizes

For non-standard page sizes, for example for envelopes, two approaches are possible.

The first approach is to pretend a common paper size, e.g. `a4', and define margins to reposition the envelope on the paper.

For example

    # Envelope A6, landscape, on A4 paper
    type e6
      paper a4
      landscape
      leftmargin 134
      bottommargin 97
      left 70
      top 60

The second approach is to explicitly specify the paper dimensions. Disadvantage is that some PostScript viewers cannot handle this correctly (GhostScript does it okay, GhostView does not).

For example:

    # Envelope A6, landscape
    paper _a6l 148.5 105  # width > height implies landscape
    type xa6
      paper _a6l
      left 70
      top 60

THE INPUT TEXT

The input is considered to be made up of text lines, each of which are printed on the labels. The encoding used is ISO-Latin-1.

A text line that starts with a double slash is printed using an italic font (after removing the slashes). A text line that starts with a double bar is printed using a bold font (after removing the bars). A text line that starts with bar-slash or slash-bar is printed using a bold-italic font (after removing the bar and slash).

In the text, the following substitutions are made:

  • Three consecutive periods are printed as an ellipsis.

  • Three consecutive minus signs are printed as a long dash.

  • Two consecutive minus signs are printed as a medium dash.

  • Straight quotes ' and " are printed as curly quotes.

  • Octal codes \336 and \320 are printed as a straight single / double quite. Deprecated.

The program recognises dutch zip codes and will print a KIX barcode under the address if it can distill the KIX code from the address. If this fails, the KIX code can be specified explicitly as the last line of the input. For example, the following two entries produce identical results:

    H.J. Hekking
    Dorpsstraat 5
    1234 AB  Juinen

    H.J. Hekking
    Dorpsstraat 5
    1234 AB  Juinen
    1234AB5

In the second entry, the KIX code was explicitly specified.

The program will issue a warning if it could not determine the KIX code from the address.

KIX code processing can be suppressed with the -nokix command line option.

THE OUTPUT POSTSCRIPT DOCUMENT

The generated PostScript output is conformant to Adobe Structuring Conventions version 3.0.

The fonts required for printing are not included in the PostScript output. If you use non-standard PostScript fonts, you will need a print spooler that is capable of providing the necessary fonts to the printer. Alternatively, the font files can be inserted in the PostScript preamble that follows the program text.

BUGS AND DEFICIENCIES

There is no protection against text running off the label, if the text is too long.

Fonts and font sizes are hard-wired.

AUTHOR AND CREDITS

Johan Vromans (jvromans@squirrel.nl) wrote the program.

The KIX code font included in the kit is created by Hendrik Jan Thomassen <H.J.Thomassen@ATComputing.nl>.

COPYRIGHT AND DISCLAIMER

This program is Copyright 1992,1999 by Squirrel Consultancy. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" which comes with Perl.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Perl Artistic License for details.