PostScript::MailLabels modules - create postscript for printing on mailing label stock
===========================================================

TABLE OF CONTENTS
-----------------

1. Description
2. Availability
3. Prerequisites
4. Installation
5. Running Tests
6. Demonstration scripts
7. Bugs
8. Change History
9. Copyright
10. Author Information



1. DESCRIPTION
--------------

This is a pair of modules for calibrating, testing, and printing mailing
labels on standard label stock. It may also be used for other tasks that
print standard fields onto a regular grid.

The modules are :

PostScript::MailLabels
PostScript::MailLabels::BasicData

BasicData is called by MailLabels and is not meant to be called by anyone else.

MailLabels has three main outputs, in postscript(tm).

1. A calibration sheet for measuring the print borders and centering of your
   printer
2. A test sheet showing where the edges of the labels should be. This is used 
   to make the final adjustments to the calibration
3. The address labels themselves


2. AVAILABILITY
---------------

  The newest version (which should be considered a beta version) is available
  through my home page:
    http://www.ajackson.org/software/maillabels
  Feel free to try it out.

  The current (non-beta) version of this module is available from your nearest
  CPAN site.

  The two will frequently be the same.

3. PREREQUISITES
----------------

Perl 5.005_03 is where I developed this. It may work with earlier versions,
but I haven't tried it. I'm not too sophisticated, so I'd be a little
surprised if I used anything not in 5.003 for example.

4. INSTALLATION
---------------

To install, just type
  perl Makefile.PL
  make
  make test
  make install

For help with Makefile.PL, try
perldoc ExtUtils::MakeMaker

If you wish to install in a non-standard place, use 

perl Makefile.PL LIB=~/lib PREFIX=~

5. RUNNING TESTS
----------------

Three PostScript(tm) files will be created by the tests. You should view
these with ghostview, ghostscript, or your favorite viewer. Or print them.

I can't imagine the tests failing, unless you were missing some key part
of perl, but hey, things happen. If it fails, email me. Try running
make test TEST_VERBOSE=1 and send me the results.

6. DEMONSTRATION SCRIPTS
------------------------

In the /demo directory are some scripts that show what it can do. Hope they
make the documentation clearer.

Current demos include :

demo/diskette.pl - generate labels for 3.5 inch diskettes
demo/portuguese.pl - generate mailing labels in Portuguese on A4 paper
demo/std_business.pl - use the standard USPS field designations for labels
demo/print_addrs - simple script to make labels for Christmas Cards.
demo/testlabels.pl - same as the example in the pod. Shows everything it can do.

I now use J-Pilot and my Palm for my address book, and so I have code
on my webpage (ajackson.org) to handle reading from the J-pilot database
and generating address labels.

7. BUGS
-------

None that I know of - when you find one, let me know.

If you do report it, please include :
- version of perl
- version of MailLabel
- Operating System and version
- description of problem
- a *short* piece of code that demonstrates the problem

8. CHANGE HISTORY
-----------------

Revision history for Perl extension PostScript::MailLabels.

2.23 Tue Nov 29 20:55:38 CST 2005
	Added Avery 5526 labels per request of Wallace Winfrey

2.22 Sat Nov 26 14:25:39 CST 2005
	an small patch correcting the encoding for all fonts, with this patch you
	can use different fonts with IsoLatin encoding. Supplied by Ing. Juan 
	Manuel Calvo, Director del Centro de Cómputos, Universidad del CEMA

2.21 Sat Aug 13 17:43:36 CDT 2005
	Minor repairs to fix what patches broke (ISOLatin1Encoding), update docs
		and examples.

2.20 Sat Aug 13 16:39:54 CDT 2005
	Applied patches from Jonathan Kamens
	1) Add support for No. 9 and No. 6 3/4 envelopes.

	2) Add 5160 to the list of Avery product codes for the layout code 5160
	   (since 5160 is the product code that appeared on the box of labels that
       I bought).

	3) Add a new "orientation" setup option which can be set to "portrait"
	   or "landscape", with "portrait" being the default.

	4) Modify the generated PostScript code so that if we're in landscape
	   mode, we rotate and translate appropriately.

	5) Wrap the generated PostScript code in "gsave ... grestore" so that
	   the translation and rotation is protected (this way, e.g., you can
	   have both a calibration page and a label test page in the same
	   PostScript file without over-rotating and over-translating).

	6) Don't hard-code the list of valid paper sizes in MailLabels.pm;
	   instead, get it from BasicData.pm.

	7) To support the new landscape stuff, add a new parameter to the
	   papersize() function, "logical", to indicate whether the caller
	   wants the physical page size or the logical one.  The logical page
	   size has the width and height flipped when in landscape mode.
	   Modify calls to papersize() when appropriate to use the logical
	   rather than physical page size.

	8) Fix a typo in a comment.

2.11 Sat Nov 13 14:42:37 CST 2004
	Put in a trap to catch empty fields and set them to blank with a
	warning (Joe Zacky found this one). Also update docs to explain the 
	barcode stuff, since if you look closely, it can be confusing.


2.10 Sun Aug 29 14:00:53 CDT 2004
	Added parameters for 5167 Avery(tm) stock - thanks to Daniel J McDonald
	for supplying the parameters.

	Also added many new Avery (tm) parameters. Thanks to Summer Misherghi
	who pointed me to http://www.worldlabel.com/Pages/pageaverylabels.htm

	Added new parameter set 'freetype', to allow the user to place a text 
	string anywhere they want. Particular use is for numbering the pages.

	Code now escapes special PostScript characters (){}[]<>/% in the
	input so that they will print properly and not crash the PS interpreter.

2.02 Fri Jan 12 22:07:12 CST 2001
	Added y_gap tp Avery(tm) labels
	Updated calibration plot in BasicData to arbitrary paper size
	Minor repairs to test routine


2.00  Mon Jan  1 14:50:37 CST 2001
	Major revision. Added all of the component and label definition stuff. 
	Thanks to "Andrew Smith" <asmith at wpequity.com> for suggesting
	additional fields and inspiring the generalization.
	Thanks to Nuno Faria for assisting with the "Europeanization" of
	the code - it now works for Portuguese, and hopefully for other
	alphabets as well.
	Added pagesize so that various paper sizes are actually handled correctly.
	Minor bug fixes to PostScript::MailLabels::BasicData, now at version 1.01.


1.01  Fri Dec 29 10:00:07 CST 2000
	- bug fix version. 
		- added parameter checking and also lowercase parameters to reduce errors.
		- fixed PostScript code for boxes to work with newer ghostscript interpreters
		- added new URL's for addressbook homepage.

1.00  Wed Nov 10 21:32:53 1999
	- original version; created by h2xs 1.19


9. COPYRIGHT
------------

Copyright (c) 1999 Alan Jackson. All rights reserved.
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

10. AUTHOR INFORMATION
---------------------

Alan Jackson
alanj@ajackson.org
http://www.ajackson/org/


