README file for "pal" (Print Address Labels).
---------------------------------------------
This file is split into the following sections:
o Brief Summary of Pal
o Compilation and Installation
o Environment Variables
o Pal Configuration Files
o Using Pal
o Where to get Additional Fonts and .afm Files
o Copyright
Brief Summary of Pal
--------------------
The name "pal" is an acronym for "Print Address Labels". The purpose of
the program is to read in an ASCII file containing addresses and output
a PostScript file which can be printed onto sheets of address labels.
Two uses of pal which spring to mind are:
o Produce address labels for a direct-mail mailing shot.
o Print a full page of self-addressed labels for sticking on
the inside cover of books, or use as return-address labels on
envelopes/parcels etc.
(This second usage is helped by using the "-p" command-line option
which will print a full page of labels for each address specified in
the input file.)
Upon startup, pal reads in a configuration file that specifies the
dimensions of the page, the number of rows and columns of labels on the
page, which font should be used to print labels, the maximum font size
to use and so on. Because pal reads such information from a
configuration file (rather than have these values hardwired into the
source code), pal is versatile enough to be used with a range of
different paper sizes (notably A4 and US letter) and different
label formats.
Compilation and Installation
----------------------------
Before you try to compile pal (which can be done by typing in the
command "make pal"), you should have a brief look at the following two
files and edit them if necessary:
o Makefile
o config.h
Once you have tailored the contents of these files to suit your
computer system, the compilation of pal will _hopefully_ proceed
smoothly. (If not then get back in contact with me to let me know what
went wrong.) These two files contain some comments to guide you in
editing them. The only part of these files which I think need further
explaining are the following variables in the Makefile:
o BIN_DIR
o PAL_LIB_DIR
o PAL_FONTS_DIR
BIN_DIR is used only if you type the command "make install". In this
case, BIN_DIR specifies which directory the pal executable file should
be copied into.
PAL_LIB_DIR specifies the name of the directory where "make install"
should place any "library files" that it needs. (Currently there are
just two library files: a default configuration file called
"8x3NoMargin" and a file containing some PostScript code called
"prolog.ps".)
When pal is running it will read the Adobe Font Metrics (.afm) file of
the font that it is using to print address labels. (The font to use is
specified in the configuration file; the font specified in the default
configuration file is "Times-Roman".) For your convenience, I am
shipping two .afm files ("Times-Roman.afm" and "Helvetica.afm") with
pal. PAL_FONTS_DIR specifies the name of the directory where "make
install" should place these .afm files.
When pal tries to open a library file it will search through a path
(i.e., a list of directories) to find it. The default path, is coded
into the executable program through the Makefile; it causes pal to look
in the current directory and then in PAL_LIB_DIR.
Similarly, pal searches through a path to find .afm files. The default
path, as specified in the Makefile, causes pal to look in the current
directory and then in PAL_FONTS_DIR.
The directories which I have assigned to PAL_LIB_DIR and PAL_FONTS_DIR
in the Makefile are directories which exist on my machine but probably
do not exist on yours. However, the default paths that pal uses includes
the current directory so I suggest that you:
o Compile pal (via "make pal") and play around with it in the
current directory.
o If/when you have tested pal and are happy with it, edit the
Makefile and set the PAL_LIB_DIR, PAL_FONTS_DIR and BIN_DIR
variables appropriately for your machine. Now type in the
following commands:
make clean --- Delete files from previous compilation
make pal --- Recompile pal
make install --- copy the executable file, library
files and font files into
appropriate directories
o Alternatively, if you want to avoid recompiling pal then you
could (i) edit the Makefile to set the PAL_LIB_DIR,
PAL_FONTS_DIR and BIN_DIR variables appropriately for your
machine; (ii) type "make install"; and (iii) read the next
section to see how you can use environment variables to tell
pal what directories to search when looking for files.
Environment Variables
---------------------
The "Compilation and Installation" section mentioned that pal searches
a path for library files and another path for .afm files. If you want
to change the paths that pal searches for files then you can do so by
setting some environment variables.
Environment variable Used for
+---------------------+-----------------------------------------+
| PAL_FONT_PATH | Where to search for .afm and .pfa/.pfb |
| | files |
| | |
| PAL_LIB_PATH | Where to search for library files |
| | |
| PAL_CONFIG_FILE | Name of default configuration file |
| | (this can be overridden by the "-c" |
| | command-line option) |
+---------------------+-----------------------------------------+
If a user has some fonts then he may wish to set the PAL_FONT_PATH
environment variable to point to the directory(ies) in which the fonts
are located so that he can use them with pal.
If a user has access to several different types of address label sheets
then he may create several configuration files---one for each type of
address label sheet. (For example, I know of one brand-name of address
labels which has 24 labels per sheet arranged in 8 rows and 3 columns
and another brand-name which has 16 labels per sheet: 8 rows and 2
columns.) Alternatively, a user may have several configuration files:
one that print addresses in, say, a handwriting font and another that
prints addresses in a more formal font. If the user does not have
permission to place his configuration files in the installation
directory then he could place them in a directory of his own and set
PAL_LIB_PATH so that pal will look there.
The PAL_CONFIG_FILE, if set, specifies the default configuration file
to be used. This is only of use if you have several configuration
files.
Another good use of the environment variables is to write a short
shell-script, called "pal", which will set the environment variables
appropriately and then invoke the real pal program. This might be
useful if you have already installed pal but later reorganise your file
system and, in the process, move the location of pal library files or
fonts. Rather than recompile pal in order to tell it the new locations
for the files, you can simply write a short shell-script instead.
Pal Configuration Files
-----------------------
I have provided one sample configuration file called "8x3NoMargin". This
file is liberally commented and should be self-explanatory.
Using Pal
---------
The basic usage of pal will be "pal input-file output-file". The
input-file should contain a list of addresses (the format of this
input-file will be discussed later) and pal will write the PostScript
code to the output-file. If you omit the output-file then it defaults to
the standard output. Similarly the command "pal", with no files
specified, will read from the standard input and write to the standard
output. Having pal's input/output default to stdin/stdout allows it to
be used easily as part of piped chain of commands, e.g.:
command-to-extract-addresses-from-database | pal | lpr
Command-line options:
The following are the different command-line options which you can
pass to pal:
-h Write a help message to the screen and quit.
-c<config-file> Specifies <config-file> as the name of the
configuration file that pal should read.
-d<thickness> Draws a box around each address label. This
is really only be of use if you are creating
a new configuration file (or modifying an
existing one) and are having trouble
accurately specifying the dimensions and
placement of labels on the sheet of paper.
In such cases it is a good idea to print out,
onto a plain sheet of paper, a page of dummy
labels (the "-p" option can be useful for
this) with boxes drawn around each label as a
guideline. Then hold this sheet of paper
behind a sheet of blank address labels and
check that the boxes line up with the
boundaries of the labels.
The width of the lines used to draw the boxes
is given by <thickness>. A value of 1 will
probably be suitable. Increasing this value
will result in thicker lines and decreasing it
(e.g, 0.5 or 0.2) will result in thinner lines.
-p Output a page of labels for each address
given in the input.
-q Quiet mode: tells pal not to print out any
warning messages.
-f Pal searches in the PAL_FONTS_PATH directories
for the Adobe Font Metrics (.afm) file
of the font specified in the configuration
file. Pal will also search these directories
for the actual font file itself (stored in
either .pfa or .pfb format). If can find the
font file then, by default, it will include
it in the output PostScript file. The purpose
of this is to allow you to use pal with any
font you may own, rather than just the fonts
which happen to be built into the printer.
The "-f" option tells pal to _not_ include the
font file (.pfa or .pfb) in the output. You
would use this option if you knew that the
font in question had previously been
down-loaded to the printer.
Input-File Format:
The format of input files is simple. There are only three rules to
remember:
o Addresses are separated by one or more blank lines. (Note
that blank lines are just that: they do not even contain any
spaces or tabs.)
o Comments in the input file start with a percent sign (%) and
continue until the end of the line. If you want to include a
percent sign as part of an address then precede it with a
backslash (\%).
o Pal supports _some_ (but not all) combinations of accented
characters. The way to obtain an accented character is to use
a three-character combination where the first character is a
backslash (\), the second indicates which accent to use (see
the table below), and the third character is the letter you
want the accent to appear on.
character accent obtained example
+-----------+-------------------+---------+
| ` | grave | \`a |
| ' | acute | \'a |
| ^ | circumflex | \^a |
| ~ | tilde | \^a |
| o | ring | \oa |
| , | cedilla | \,c |
| " | dieresis | \"i |
+-----------+-------------------+---------+
If you try to obtain an accented character which is not
available in the font being used then pal will print a warning
message. (You can suppress these warning messages with the
"-q" command-line option.)
The following example illustrates the format of an input file containing
two addresses.
----cut here----
J\'an\`e D\"oe
24 Baker Street
Beverly Hills
CA 90210
% Tel: 555-1287 (work)
% 555-3278 (home)
Ciaran McHale% This is a comment
Distributed Systems Group% And another one
Department of Computer Science
Trinity College
Dublin 2
Ireland
%
Email: cjmchale@dsg.cs.tcd.ie
Tel: +353-1-7021539
----cut here----
The first address shows some accented characters being used. It also
shows how comments can be used to store extra information about a person
that you do not want to appear on address labels, e.g., telephone
numbers or email addresses.
The second address illustrates some subtle points about the usage of
comments.
Firstly, if you are going to place a comment on the same line as some
text (as done in the first two lines of this address) then the comment
should start immediately after the text, _without_any_ intervening
spaces. If you _did_ have spaces before the start of the comment then
pal would think that these spaces are part of the address and would
print them out. Since spaces do not make any marks on the printed page,
you may think that it would not make any difference if they were
printed out; however, it is possible that pal might decide to use a
smaller font size to print the address if the apparent width of the
text (including the width of excess spaces at the end of a line) is too
wide to fit onto a label.
Secondly, the way to include a blank line in an address is to place at
least one space onto the "blank" line. Since spaces in the input are
invisible to humans, it is a good idea to place a comment after the
space, just to let you know that it is there. In the above example,
this is done to get a blank line between the main part of the address
and the email address. While you would not normally want to print
someone's email address & phone number onto an address label, you may
want to print your own postal and email address, and phone and fax
numbers onto labels which you can then stick on the inside cover of
books etc.
Where to get Additional Fonts and .afm Files
--------------------------------------------
The Adobe ftp site (ftp.adobe.com) contains the .afm files for most, if
not all, Adobe fonts. Thus if you want pal to use a particular font
that is built into your printer but you do not have the font's .afm
file then you might be able to obtain it via anonymous ftp from
ftp.adobe.com. If you do not have ftp access then you can retrieve the
same files from the Adobe mail server. Send an email with _just_ "help"
in the Subject: line to "ps-file-server@adobe.com" for instructions on
how to use this mail server. When you get the .afm file, place it in one
of the directories listed in PAL_FONTS_PATH.
Sometimes you may see advertisements in computer magazines selling
fonts. The comp.fonts FAQ posting also lists some ftp sites where you
can obtain some free, or shareware, fonts. If you do obtain a font then
it should come as a set of two files. The font itself is a program and
will be in a file whose ending is either ".pfa" or ".pfb". (The only
difference between .pfa and .pfb files is that the latter is a
binary/compressed version of ".pfa"; utilities are available to
translate between .pfa and .pfb formats.) Along with the font file,
there should also be a .afm file which contains font metrics (the
dimensions of all characters in the font, kerning information etc.).
If you obtain any extra fonts then place the .pfa (or .pfb) file along
with the .afm file in a directory listed in PAL_FONTS_PATH so that pal
can find them and will be able to include the font in the output
PostScript file.
Copyright
---------
o This program is not copyrighted.
o This program comes "as is", with no expressed or implied
warranty.
o You are welcome to use this program as you wish. For example,
you can modify it, use it as part of other programs, sell it,
or give it away for free.
o Unlike Gnu software, this program is _not_ "copylefted".
