			     INTRODUCTION
			     ============
				   
		      The Perl 5 Reference Guide

The Perl Reference Guide is a typeset quick reference guide to Larry
Wall's Perl program.

It contains a concise description of all Perl 5 statements, functions,
variables and lots of other useful information. The Guide is based on
Perl version 5, patchlevel 4.

The purpose of the Reference Guide is to aid in the use of Perl, to
look up the syntax of specific functions, statements and the meaning
of built-in variables. It is *NOT* a self-contained user guide - basic
knowledge of the Perl language is required. It is *NOT* complete -
some of the more obscure variants of perl constructs have been left
out. But all functions and variables are mentioned in at least one way
they can be used.

The Reference Guide is designed and created by Johan Vromans using the
LaTex typesetting system. The distribution contains a ready-to-use
PostScript file. A special formatting tool, written in Perl, makes it
possible to reformat this PostScript output for reproduction in a
number of formats.

The version number of the Reference Guide is coupled to the version of
Perl, e.g. 5.012.2 means: the second release suitable for Perl 5
patchlevel 12. (This is an example. There is no Perl 5 patchlevel 12 (yet?))

The Reference Guide is also available as a booklet published by
O'Reilly & Associates, see below.

INSTALLATION
============

 1. Unload the distribution

    After unloading the distribution, you will have the following
    files in a suitably named sub-directory:

	README	    - this file
	Makefile    - makefile (should be system independent)
	parr.pl	    - reformat and rearrange tool
	Layout	    - description of the format
	MANIFEST    - a list of files
	refbase.ps  - PostScript source for the Reference Guide
	testbase.ps - alignment test page
	Makefile.psutils - makefile to be used with psutils
	PROBLEMS    - known problems on certain printers

 2. Determine the paper format and alignment

    As distributed, the Makefile is configured to generate output for
    A4 (21 x 29.7 cm) paper format. Uncomment the line "PAPER=-letter"
    in the Makefile to select US Letter (8.5 x 11") format. Both
    formats should be printable on industry-standard PostScript
    printers.

    Now "make testpage.ps" and print it. The test page contains a
    scale. Find the center of the paper by folding it as illustrated
    and determine the value on the scale where the center of the paper
    intersects the scale. Add this value to the definition of HALIGN
    in the Makefile (initially 0). It is important that you modify the
    Makefile otherwise the test page will not be re-generated with the
    modified values.

    "make testpage.ps" once again and print it. Folding it should show
    that the center of the paper is at scale value 0. If not, repeat
    the process.

    For example, if your print looks like:

                                   :                           
     100                           :         0                 
     |---+---+---+---+---+---+---+-:-+---+---|---+---+---+---+---+--
                                   :                           
                                   :<- center of paper

    The value of HALIGN should be increased with 25.

    You can adjust the vertical offset by modifying VALIGN although
    this should rarely be necessary. Vertical alignment uses the same
    units as the horizontal alignment, positive offsets move the image
    down on the paper.

    NOTE: Do not print from Ghostview or other PostScript viewing
          tools since this can lead to mis-aligned prints.

    NOTE: If you have Angus Duggan's psutils package installed you can
          use Makefile.psutils instead. However, this is not
          supported by me.
          Angus' email address is <angus@harlequin.co.uk> .

 3. Create the RefGuide from the PostScript sources

    The Reference Guide should be printed double-sided, stapled in the
    middle, folded, and cut to size to have a 24-page 4.25 x 8"
    booklet. See the "Layout" document for details.

    You can use "make" to generate a new PostScript file for one of
    the following printer classes"

     - If your printer supports duplex printing, uncomment one of the
       DUPLEX defines in the Makefile and use "make refguide.ps". Send
       it to the printer while keeping your fingers crossed.

     - Use "make 2pass" to create a set of odd and even pages for
       double sided printing. First print "guide-odd.ps".
       After printing "guide-odd.ps", re-insert the sheets of paper
       into the printer tray with the correct sides up or down,
       depending on your type of printer. Now think hard: which sheet
       will get printed first? If that is the sheet that has the cover
       page on it, use "guide-even2.ps". Otherwise, use
       "guide-even1.ps".

    "make" without arguments will default to refguide.ps.

    NOTE: If you have Angus Duggan's psutils package installed you can
          use Makefile.psutils instead. However, this is not
          supported by me.

    See also the file PROBLEMS.

Comments are welcome, send them to the author.

HISTORY
=======

The first version of the Reference Guide --"reference card" it was
called then-- appeared in 1989 with Perl version 2. It was created
using an Apple Macintosh and the RagTime DeskTop publishing tool. It
was 9 pages, if I remember well. The PostScript output was extracted
from the Mac and hacked for 'normal' use with the macps program.

With Perl version 3 came the next version. A 15-page card format, and
a 16-page reference guide. This time, the Guide was created using
MicroSoft Word, again on Macintosh. Tools were supplied to manipulate
the PostScript file to suit different printing formats. In a later
version, the card format was abandoned.

Next came the Camel version, with Perl version 4. Much effort was
spent to have the abundance of new functions fit on 16 pages.

After the book appeared, I decided to rework the Guide to use more
pages, and different styles and fonts for clarity. I reworked the
MS-Word version, to find out that the resultant PostScript file had
increased from 90Kb to 180Kb! 
So I decided to start again, from scratch (well, almost) using the
LaTeX typesetting system. The resultant PostScript file is now 80Kb,
while it prints out almost identical to the 180Kb MS-Word version.

When Perl 5 came out, the Guide was reworked to include the plethora
of new features while still trying to be concise. 
I also used a scan of the Camel to create a real cover page.
Tim O'Reilly (O'Reilly & Associates, Inc.) wrote me:

    You can do this, as long as you say somewhere in your text,
    "The camel as an image associated with perl is a trademark
    of O'Reilly & Associates, Inc. and is used with permission."

    Trademarks are funny. If you don't use due diligence to protect
    them, you lose them. We've applied to treat all our cover animals
    as trademarks, so they don't get abused by other publishers, and
    we need to acknowledge them as such if they are used elsewhere.

Thanks Tim, for the permission.
The PostScript file has grown to 400Kb (including 280Kb for the cover).

O'Reilly & Associates have published the Reference Guide as a handy
booklet under the name Perl5 Desktop Reference (ISBN 1-56592-187-9).
The magenta version of the Desktop Reference is based on Perl 5.001,
the cyan covered version is based on Perl 5.003. For just $6.95 you
can save yourself the troubles of printing, aligning, adjusting,
folding, cutting and stapling.

COPYRIGHT
=========

The Perl Reference Guide is copyrighted by the author. It may be
reproduced, printed and distributed freely for non-profit purposes, as
long as the original author gets the credits, and the copyright notice
is not removed from the text. It may not be turned into a commercial
product except with written permission of the author.

---------------------------- author info -----------------------------
Johan Vromans                                     jvromans@squirrel.nl
Squirrel Consultancy                          Haarlem, the Netherlands
http://www.squirrel.nl                  http://www.xs4all.nl/~jvromans
----------------------------------------------------------------------

CREDITS
=======

I like to thank everyone who has helped me (and encouraged me) to get
the job done, and to get the results to you. Especially Tom
Christiansen and JGreely (for "parr") And Larry Wall, of course,
without whom I would have spent lots of time annoying myself.

Roy Johnson <rjohnson@shell.com> sent me a scan of the Camel that I
used to make the cover page. The cover design is based on the design
that O'Reilly made for the Reference Guide that was published with the
book "Programming Perl" and is used with permission of O'Reilly &
Associates, Inc.

For a text-only version, please contact Phil Macias
<phil@okapi.chem.sunybroome.edu>.

For a japanese version of the reference guide, please contact 
Yoshiyuki KONDO <cond@lsi-j.co.jp>.

-- PostScript is a trademark of Adobe, I assume.
$Id: README,v 5.12 1997-09-17 11:15:27+02 jv Exp $

