INTRODUCTION ============ The Perl 4.0 Reference Guide Revised: 91/07/26 The Perl Reference Guide is a typeset quick reference guide to Larry Wall's Perl program. It contains a concise description of all Perl 4.0 statements, functions, variables and lots of other useful information. The Guide is based on Perl version 4.0, patchlevel 10. 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. For best results, Tom Rockiki's dvips 5.47 should be used to generate the PostScript output. Your mileage may vary when you use other ouput mechanisms. A special formatting tool, written in Perl, makes it possible to reformat this PostScript output for reproduction in a number of formats. If you cannot run this tool, you do not need the information either. INSTALLATION ============ 1. Unload the distribution After unloading the distribution, you will have the following files: README - this file ChangeLog - description of changes Makefile - make file parr - reformat and rearrange tool The LeTeX kit includes refbase.tex - LaTeX source for the Reference Guide refbase.sty - LaTeX style for the Reference Guide The PostScript kit includes refbase.ps - pre-generated PostScript base 2. Create the PostScript base file You can skip this step if you already have a pre-generated PostScript base file. This step requires the LaTeX typesetting system, and dvips version 5.47 or later. - Use "make refbase-ps" (a dash, not a dot) to create a new PostScript file from the LaTeX source. This file can be printed normally. NOTE: dvips must be instructed to use a4 format paper ('-t a4') even if you intend to print on a different format! 3. Create the RefGuide from the PostScript base As distributed, the Makefile is configured to generate output for A4 (21 x 29.7 cm) paper format. Use "make PAPER= ..." to select US Letter (8.5 x 11") format. Both formats should be printable on all industry-standard PostScript printers. You can use "make" to generate a new PostScript file for one of the following formats: - Use "make refguide.ps" to create a guide formatted in 10 pages of 2-column text. It should be printed double-sided, stapled in the middle, folded, and cut to size to have a 16-page 3.5 x 8" booklet. - Use "make 2pass" to create a set of odd and even pages for double sided printing. First print "guide-odd.ps". Then put the paper back in the tray, and print either "guide-even1.ps" or "guide-even2.ps", depending on the way your printer arranges the printed paper. "guide-even1.ps" is for printers with correct output stacking like Apple LaserWriter II. "guide-even2.ps" is for printers with reverse output stacking, like old Apple LaserWriters. In other words, after printing "guide-odd.ps", if the text of the cover page is on top -- use "guide-even1.ps". But if you're looking at the text of pages 9/10 -- use "guide-even2.ps". "make" without arguments will default to refguide.ps . If your printout is not correct, feel free to change the figures in subroutine 'twoup' of the 'parr' program. Comments are welcome, send them to the author. IF YOU DON'T HAVE A POSTSCRIPT PRINTER ====================================== Look in perlref.sty for comments with ">>>>" as a guide. The output will not be as perfect, but still very useful. HISTORY ======= The first version of the Reference Guide --"reference card" is was called then-- appeared in 1989 with perl version 2.0. It was created using an Apple Macintosh and the RagTime DeskTop publishing tool. It was 9 pages, I believe. 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, still 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 4.0. Lots of measurements had been taken 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. CREDITS ======= The Perl Reference Guide is copyrighted by the author. It may be reproduced, printed and distributed freely, 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 Multihouse Research, Doesburgweg 7, 2803 PL Gouda, the Netherlands tel. +31 1820 62911, fax. +31 1820 62500 email: ---------------------------------------------------------------------- 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. -- PostScript is a trademark of Adobe, I assume. @(#)@ README 4.2.1