home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / perl / perlref-4.036.1 / README < prev    next >
Encoding:
Text File  |  1993-05-17  |  6.4 KB  |  165 lines
  1.                  INTRODUCTION
  2.                  ============
  3.  
  4.              The Perl 4.0 Reference Guide
  5.  
  6.             Revised: 93/05/18
  7.  
  8. The Perl Reference Guide is a typeset quick reference guide to
  9. Larry Wall's Perl program.
  10.  
  11. It contains a concise description of all Perl 4.0 statements,
  12. functions, variables and lots of other useful information. 
  13. The Guide is based on Perl version 4.0, patchlevel 36.
  14.  
  15. The purpose of the Reference Guide is to aid in the use of Perl, to
  16. look up the syntax of specific functions, statements and the meaning
  17. of built-in variables.  It is *NOT* a self-contained user guide -
  18. basic knowledge of the Perl language is required. It is *NOT* complete
  19. - some of the more obscure variants of perl constructs have been left
  20. out.  But all functions and variables are mentioned in at least one
  21. way they can be used.
  22.  
  23. The Reference Guide is designed and created by Johan Vromans using the
  24. LaTex typesetting system. For best results, Tom Rockiki's dvips 5.47
  25. should be used to generate the PostScript output.
  26. Your mileage may vary when you use other ouput mechanisms.
  27.  
  28. A special formatting tool, written in Perl, makes it possible to
  29. reformat this PostScript output for reproduction in a number of
  30. formats.  If you cannot run this tool, you do not need the
  31. information either.
  32.  
  33. The version number of the Reference Guide is coupled to the version of
  34. Perl, e.g. 4.019.2 means: the third release suitable for perl 4
  35. patchlevel 19. 
  36.  
  37. INSTALLATION
  38. ============
  39.  
  40.  1. Unload the distribution
  41.  
  42.     After unloading the distribution, you will have the following files:
  43.  
  44.     README        - this file
  45.     ChangeLog   - description of changes
  46.     Makefile    - make file
  47.     parr        - reformat and rearrange tool
  48.     Layout        - description of the format
  49.     MANIFEST    - a list of files
  50.     refbase.tex - LaTeX source for the Reference Guide
  51.     refbase.sty - LaTeX style for the Reference Guide
  52.     refbase.ps  - pre-generated PostScript base
  53.  
  54.  2. Create the PostScript base file
  55.  
  56.     You can skip this step if you already have a pre-generated
  57.     PostScript base file.
  58.     This step requires the LaTeX typesetting system, and dvips version
  59.     5.47 or later.
  60.  
  61.     - Use "make refbase-ps" (a dash, not a dot) to create a new
  62.       PostScript file from the LaTeX source. This file can be printed
  63.       normally. 
  64.  
  65.     NOTE: dvips must be instructed to use a4 format paper ('-t a4')
  66.       even if you intend to print on a different format!
  67.  
  68.  3. Create the RefGuide from the PostScript base
  69.  
  70.     As distributed, the Makefile is configured to generate output for
  71.     A4 (21 x 29.7 cm) paper format. Use "make PAPER= ..." to select US
  72.     Letter (8.5 x 11") format.  Both formats should be printable on
  73.     all industry-standard PostScript printers.
  74.  
  75.     You can use "make" to generate a new PostScript file for one of
  76.     the following formats:
  77.  
  78.      - Use "make refguide.ps" to create a guide formatted in 10 pages
  79.        of 2-column text. It should be printed double-sided, stapled in
  80.        the middle, folded, and cut to size to have a 16-page 3.5 x 8"
  81.        booklet.
  82.  
  83.      - Use "make 2pass" to create a set of odd and even pages for
  84.        double sided printing. First print "guide-odd.ps". Then put the
  85.        paper back in the tray, and print either "guide-even1.ps" or
  86.        "guide-even2.ps", depending on the way your printer arranges
  87.        the printed paper.
  88.        "guide-even1.ps" is for printers with correct output stacking like
  89.        Apple LaserWriter II. 
  90.        "guide-even2.ps" is for printers with reverse output stacking,
  91.        like old Apple LaserWriters. 
  92.        In other words, after printing "guide-odd.ps", if the
  93.        text of the cover page is on top -- use "guide-even1.ps".
  94.        But if you're looking at the text of pages 9/10 -- use
  95.        "guide-even2.ps". 
  96.  
  97.     "make" without arguments will default to refguide.ps .
  98.  
  99.     If your printout is not correct, feel free to change the figures in
  100.     subroutine 'twoup' of the 'parr' program. The file Layout
  101.     describes in more detail how the Guide should look like.
  102.  
  103.     On printers that support it, duplex printing is done.
  104.  
  105. Comments are welcome, send them to the author.
  106.  
  107. IF YOU DON'T HAVE A POSTSCRIPT PRINTER
  108. ======================================
  109.  
  110. Look in perlref.sty for comments with ">>>>" as a guide.  The output
  111. will not be as perfect, but still very useful.
  112.  
  113. HISTORY
  114. =======
  115.  
  116. The first version of the Reference Guide --"reference card" is was
  117. called then-- appeared in 1989 with perl version 2.0. It was created
  118. using an Apple Macintosh and the RagTime DeskTop publishing tool.
  119. It was 9 pages, I believe. The PostScript output was extracted from
  120. the Mac and hacked for 'normal' use with the macps program.
  121.  
  122. With perl version 3 came the next version. A 15-page card format, and
  123. a 16-page reference guide. This time, the Guide was created using
  124. MicroSoft Word, still on Macintosh. Tools were supplied to manipulate
  125. the PostScript file to suit different printing formats.
  126. In a later version, the card format was abandoned.
  127.  
  128. Next came the Camel version, with perl 4.0. Lots of measurements had
  129. been taken to have the abundance of new functions fit on 16 pages.
  130.  
  131. After the book appeared, I decided to rework the Guide to use more
  132. pages, and different styles and fonts for clarity. I reworked the
  133. MS-Word version, to find out that the resultant PostScript file had
  134. increased from 90Kb to 180Kb! 
  135. So I decided to start again, from scratch (well, almost) using the
  136. LaTeX typesetting system. The resultant PostScript file is now 80Kb,
  137. while it prints out almost identical to the 180Kb MS-Word version.
  138.  
  139. CREDITS
  140. =======
  141.  
  142. The Perl Reference Guide is copyrighted by the author. It may be
  143. reproduced, printed and distributed freely, as long as the original
  144. author gets the credits, and the copyright notice is not removed from
  145. the text. It may not be turned into a commercial product except with
  146. written permission of the author.
  147.  
  148. ---------------------------- author info -----------------------------
  149.                 Johan Vromans
  150.  Multihouse Research, Doesburgweg 7, 2803 PL  Gouda, the Netherlands
  151.            tel. +31 1820 62911, fax. +31 1820 62500
  152.               email: <jv@mh.nl>
  153. ----------------------------------------------------------------------
  154.  
  155. I like to thank everyone who has helped me (and encouraged me) to get
  156. the job done, and to get the results to you. Especially Tom
  157. Christiansen and JGreely (for "parr") And Larry Wall, of course,
  158. without whom I would have spent lots of time annoying myself.
  159.  
  160. For a japanese version of the reference guide, please contact 
  161. Yoshiyuki KONDO <cond@lsi-j.co.jp>.
  162.  
  163. -- PostScript is a trademark of Adobe, I assume.
  164. @(#)@ README    4.2.6
  165.