WELCOME TO MACPERL 5

This is Perl 5, ported to the Mac by Matthias Neeracher <neeri@iis.ee.ethz.ch>
Feel free to give this program away according to the terms stated 
in the README file.

System Requirements
-------------------

MacPerl5 requires System 7.

Installing
----------

The MacPerl application doesn't need any installation beyond the help setup 
described below.

To install the MPW Perl tool, follow the instructions in �Install.MPW_Perl�.

The installer for this product was created using Installer VISE Lite
from MindVision Software. For more information on Installer VISE Lite,
contact:

MindVision Software
7201 North 7th Street
Lincoln, NE 68521-8913

Voice: 402-477-3269
Fax: 402-477-1395

Internet: mindvision@mindvision.com
http://www.mindvision.com

Online Help
-----------

MacPerl 5 comes with a considerable amount of pod based online help. For this
help to work, make sure you have:

 - "MacPerl Help" and the "pod" folder in the same folder as your MacPerl
   application.
 - A recent version of Internet Config (Version 1.4 is
   bundled with your distribution).
 - Set up Internet Config with a helper for �http�, set to a WWW Browser, and 
 	the �Shuck� application as the helper for �pod�. 

Bugs, Suggestions, Feedback
-----------------------------

Please send your bug reports and/or fixes to <neeri@iis.ee.ethz.ch> 

Mailing list
------------

There is a mailing list for announcing new releases, sharing scripts, and 
discussions about how to make MacPerl change your life. To subscribe, send
the following mail:

----------------
To: mac-perl-request@iis.ee.ethz.ch

subscribe
----------------

Ftp sites
---------

If you have internet access, you can obtain the newest versions of Perl by 
anonymous ftp from one of the following address:

sunsite.cnlab-switch.ch [195.176.255.9]      	software/platform/macos/perl

This site is mirrored in a huge number of CPAN (Common Perl Archive Network) 
mirror sites. Accessing the url http://www.perl.com/CPAN/ports/mac/ will
lead you to the mirror closest to you.


Matthias Neeracher					Office:	+41 1 274 14 08
Hohenklingenstrasse 19				Fax:		+41 1 274 14 14
8049 Zuerich							Home: 	+41 1 341 85 06
SWITZERLAND								Email:	<neeri@iis.ee.ethz.ch>

DISTRIBUTIONS

MacPerl is arranged into a number of distributions, named according to
the following scheme:

Mac_Perl_520r4_appl.bin
^        ^   ^ ^    ^
MacPerl  |   | |    MacBinary Suffix
         |   | Distribution Component
         |   Perl Patchlevel
         MacPerl Release

Currently the following components are available:

  appl           The MacPerl application (Dynamic PowerPC/Small 68K), all
                 libraries and documentation.
  tool           The Perl MPW Tool (Dynamic PowerPC/Small 68K) and scripts.
  bigappl        The MacPerl application (Dynamic PowerPC/Big 68K).
  bigtool        The Perl MPW Tool (Dynamic PowerPC/Big 68K).
  appl_cfm68K    The MacPerl application (Dynamic PowerPC/Dynamic 68K).
  src            The MacPerl source code.
  appl_only      Only the MacPerl application (Dynamic PowerPC/Small 68K)
                 without libraries and documentation.

"Small" means that the application doesn't have the Mac Toolbox modules or
the GD module compiled in (but it still will be a fully functional Perl
otherwise).
"Big" means that the application has those modules compiled in.
"Dynamic" means that the application doesn't have those modules compiled in,
but is able to load them (and arbitrary other modules) as dynamic libraries
and thus behaves as if they were compiled in.

You should install distributions as suggested in the figure below, from bottom
to top (i.e., to get the big MPW tool, install appl, then tool, then bigtool).

                        +---------+-----+
                        | bigtool | src |
+---------+-------------+---------+-----+
| bigappl | appl_cfm68K |      tool     |
+---------+-------------+---------------+
|              appl                     |
+---------------------------------------+

REVISION HISTORY

The person in [] is usually the key person to have convinced me to fix a 
bug or add a feature. Everyone mentioned in [] should be mentioned in the
MacPerl5 about box (Yes, your name could be there, too!).

5.2.0r4 17Apr98
 - Added %Mac::Speech::Voice [Chris Nandor].
 - Added Chris Nandor's AppleEvent Tutorial and information about the 
   forthcombing MacPerl book.
 - Fixed example in Mac::Processes [Kevin Reid].
 - Saving with nondefault options was unreliable [Stephan Somogyi].
 - Hardcoded paths are now shown in preferences dialog as a reminder 
   [Marcel Riechert].
 - Suspend/Resume events were sometimes swallowed.
 - Clicking in other windows when a nonmodal dialog was in front would crash
   [Kevin Reid].
 - Broke Mac::Fonts exports [Kevin Reid].
 - Found another gremlin adding empty environment variables [Chris Nandor].
 - Mac::Dialogs:SetDialogItemProc was broken [Kevin Reid].
 - Added Mac::QuickTimeVR [Christian Dippel], Mac::Sound [Kevin Lenzo] and 
   Mac::TextEdit modules.
 - AppleScript version property was stuck at 5.1.0 [Stephan Somogyi].
 - Edit menu commands while a MacPerl window was in front would crash [Sean Burke].
 - Adapted code to latest version of Universal Headers.
 - Drawing into a non-front window would sometimes go to the wrong window
   [Alan Fry].
 - Complex toolbox using scripts suffered from massive reentrancy problems in
   the event handlers. As a consequence, even handling has now been substantially
	reorganized: As soon as active event handling is turned on with use Mac::Events.
	Only explicit calls to WaitNextEvent or ModalDialog will get and handle events.
	[Chris Nandor].
 - If no Internet Config handler for pod is installed, MacPerl will now silently
   install Shuck [John Draper].
 - Opening a file in the external editor now brings that editor to the front
   [Paul DuBois].
 - MacPerl would provoke too many mouse moved events.
 - The stack size is now set to a fraction of the application partition size,
   so increasing the application partition can help in cases of massive 
	recursion [Elton Hughes].
 - The "lib" directory path is now hardcoded, so tainted code can use libraries
   more easily [Chris Nandor].
 - Another fix for environment variables [Paul Schinder].
 - Under obscure circumstances, file handles would get confused across script
   boundaries [Angus McIntyre].
 - Disabled -u option, which would not do anything reasonable on a Mac 
   [Vicki Brown].
 - Updated GD module [Chris Nandor].
 - Various minor fixes to the toolbox modules [Chris Nandor, Alan Fry, Rich Morin].
 - Added new, not yet documented, API to schedule Perl code for execution at 
   interrupt time.
	
5.1.9r4	13Jan98
 Few improvements over 5.1.8, but I wanted to build the best possible release for
 the CD-ROM.
 - Fixed inappropriate stripping of ':' in File::Find [Rich Morin].
 - Made GetNewDialog accessible again [Frank Alvani].
 - Cranked 68K optimization level back up since a new compiler is out.

5.1.8r4  07Jan98
 - 68K versions would fail to spin the cursor [Brian Matthews].

5.1.7r4	05Jan98
 - Due to a compiler bug, length() would return 0 in all 68K versions 
   [Paul Schinder].
 - Changes to $[ would persist across script executions [Xah Lee].
 - Some newer toolbox modules were omitted from BigMacPerl [Brian Matthews].

5.1.6r4	31Dec97
 - Added Chris Nandor's Appletalk code to IO::Socket.
 - Various improvements in the toolbox modules, notably:
   - Added support for accessing the fields of a ControlHandle.
	- Added routine Dialogs::GetDialogItemControl [].
	- Added methods item_control, item_hilite and item_value to 
	  MacDialog.
	- Added more alias routines to Mac::Files [Chris Nandor].
	- Added filename mappings to Mac::InternetConfig [Chris Nandor].
	- Fixed MacPerl.pm module [Xah Lee].
	- Corrected packing of Appletalk addresses [Paul Schinder].
 - Lookups of symbols starting with the first character of a window used
   to misbehave [Xah Lee, I believe].
 - Environment variables would get scrambled under certain circumstances
   [Adam Schneider].
 - The first Perl script to run in the application after startup used to
   have overly buffered standard streams [Brian Matthews].
 - MacPerl now displays the code architecture (68K, PowerPC, CFM68K) and 
   the patchlevel in the About... dialog [Tim Rand].
 - Replaces sort implementation with more efficient version where Chris 
   will find it harder to find a pathological case [Chris Nandor].
 - Fixed permission bug in sysopen() [Chris Nandor].
 - $0 could only be set to strings of a limited length [Brian Matthews].
 - Filename globbing can now deal with whitespace, provided it is
   quoted [Tom Harrington].
 - Changes to $^O erroneously persisted across script executions 
   [Chris Nandor].
 - The modification times in the folders of new files were set to absurd 
   values [Sean Burke].
 - Added variable $MacPerl::Architecture containing the code architecture.
 - Fixed behaviour of double-clicks in MacPerl::Pick in list context 
   [Brian Matthews].

5.1.5r4		10Nov97
 - Fixed various bugs in the toolbox libraries, added examples that were
   left out of the distribution [Dan Herron, Chris Nandor].
 - Made CFM68K variant functional again, turned it into fat binary.
 - Added Internet Config to the distribution again.
 - Running a program twice under the debugger would crash [Will Merrill].
 - Incorporated Paul Schinder's ports of libnet and LWP.
 - Added editor for global environment variables [Paul Schinder].
 - Universal support was broken [Paul Schinder].
 - Defaults in StandardFile.pl were broken [Manfred Lauer].
 - (Hopefully) repaired all .pl files whose XCMDs had been omitted
   [Paul Schinder].

5.1.4a	10Oct97
 - Fixed severe bugs in the MPW tool installation [Martin Heller].

5.1.4		05Oct97
 - Made Command-. more reliable and also added a menu command for it.
 - Expanded toolbox documentation considerably.
 - The MPW Tool distribution now simply installs on top of the application
   distribution, which makes it a lot smaller [Martin Heller].
 - Add %#s format to printf for Pascal strings.
 - Rewrote all toolbox interfaces to use strict; introduced a lot more structs;
   rewrote hash based structs to object based structs.
 - FindFolder.pl had lost its XFCN resource and thus would no longer work
   [Paul Schinder].
 - File::Copy::move would sometimes destroy the target file when
   the source file didn't exist. 
 - Fixed treatment of paths starting with a space [Paul Schinder].
 - MacPerl::Pick is now context sensitive: In scalar context, picks
   a single item, in array context, picks multiple items
	[Brian Matthews]. Also fixed treatment of arrow keys.
 - Safe/Opcode modules now should work.
 - Compiled without DEBUGGING option, which should speed things up.
   This only affects the -D option, not -d.

5.1.3r2	21Jan97
 - Another attempt at runtime applications [Scott Weaver].

5.1.2r2	19Jan97
 - Choosing a file from one of the Apple Menu submenus under some 
 	versions of Apple Menu Options would crash [Kevin Cutts].
 - Opening a file would crash under obscure circumstances
 	[Angus McIntyre].
 - Socket.pm was broken in 5.1.1 [Paul Schinder].
 - Removed debugging print statements in timelocal code [Paul Schinder].
 - Added Speech Recognition support [Kenneth Albanowski].
 - Added "MacPerl Scripts" folder whose items get added to script
 	menu.
 - Fixed bug in GD [Ken Stuart].
 - Fixed support for deferred scripts, so MacPerl scripts can
 	now queue successor scripts.
 - Added "One Liner" script to simulate a command line. It even
 	does a bit of globbing [Devin Ben-Hur].
 - Bundled CGI glue [as suggested by Peter Lewis].
 
5.1.1r2	05Jan97
 - MacPerl would silently overwrite locked files [Robert Decker].
 - Saving runtime applications was broken.
 - Converting a droplet to a plain text file was broken.
 - Truncating the console din't work correctly [Alan Fry].
 - Linking with libmoto for some performance improvement [William Middleton].
 - Fixed numerous bugs in Mac::AppleEvents [Chris Nandor]. Rewrote
 	AEStreams interface OOP style.
 - Added documentation for Mac::Files [William Birkett].
 - Added some Alias Manager routines.
 - Changed color of small icons so they can highlight when something is
 	dropped on them [Lasse Petersen].
 - Added Macintsh specific (GUSI) constants and packing to Sockets.
 - Added Text-To-Speech support.
 - Fine tuned cursor spinning.
 - Improved error pop-up.

5.1.0r2	21Oct96
 - Upgraded the Perl core to patchlevel 5.002_01. This should cause several bugs
   in the perl core to vanish.
 - Made MakeMaker work on the Mac with lots of help and moral support from
   Andreas K�nig.
 - Many toolbox modules now included. Added a few examples in :ext:
 - Added "Shuck", a direct POD viewer, as a lightweight documentation
   alternative to WWW browsers. To use it, open Internet Config and 
	add "Shuck" as the helper for "pod".
 - Tried fixing unsigned long problems with time values [Stewart Holt].
 - Modified and unmodified scripts had different current directories for
	"Run Front Window" [Matthias Schmitt].
 - Stop hogging the preferences file, only open it when immediately 
   needed [Toni Harbaugh]
 - Fix MacPerl::Quit to work for fat runtimes. Also introduce symbolic�
   constants [Tom Holub].
 - MacPerl::Ask() was broken when the user specified an empty string [Sam Choukri].
 - Command-. for the 68K MPW tool was broken for a long time 
   [Paul Patton, Chris Thorman].
 - Horizontal scroll bar thumb actions were accidentally misinterpreted as 
   vertical actions [Alan Fry].
 - Fixed various problems with BBEdit interaction [Brian Foy]
 - Fixed hardcoded chararacters in ftp.pl [Danny Thomas]
 - Work around integerizing problem affecting Time::Local [Diller Ryan]

5.0.7r1m 12Mar96
 - Printing \007 to the MacPerl console window now causes a beep 
   [Janis Greenberg].
 - The jump command did not work for droplets.
 - Runtimes were broken [lots of people, but I think it was Robert Coie who 
   first did the research on what was causing the crashes].
 - Some operations on bitvecs worked only the first time [reported by Paul Duda,
   fixed by John Peterson]
 - The MPW tool would crash on 68K machines [Guy Greenbaum]
   
5.0.6r1m 01Feb96
 - Redirecting STDIN would not work with <> [J�rgen Christoffel].
 - After the first script execution, STDOUT would become unbuffered 
   [Jeff Johnson].
 - Perl would crash when running two CGI scripts in sequence (actually
   a bug in the CGI glue) [Steve Goodwin].
 - localtime, gmtime, and related routines and libraries exhibited various
   problems [Peter Creath, Brad Cox, Dave Wodelet].
 - Fixed a memory leak in sort [Vicki Brown].
 - Performance in the background and for CGIs should be significantly improved.
 - Performance for reads in raw mode massively improved [Dick Karpinski].
 - Added a new interaction mode "Duplex" and tried to improve the documentation
   of interaction modes in MacPerl.FrontEnd with actual AppleEvent logs.
 - Implemented crypt(), which now makes MacPerl officially a munition.
 - Cleaned up balloon help texts.
 - "Check Syntax" now works analogously with "Run Script", i.e., both on the front
   window and on a Standard file dialog [Angus McIntyre]
 - The operations working on the "front window" have subtly redefined that term
   to exclude console windows. This allows one to run a script again even if the
	output window is in front [Anybody wanna take credit for that suggestion?].
 - New environment variable "MACPERL" contains the path of the folder containing
   the MacPerl application.
 - Added a few automatic and semiautomatic ways to launch Internet Config. Among
   other places, you now find IC in the Preferences dialog, and MacPerl suggests
	that you launch IC if the file helper is missing.
 
5.0.5r1m 29Dec95
 - Fixed a disastrous bug with saving Droplets [Phil Ames]. The
   MPW Tool has not changed except for the version number.

5.0.4r1m 27Dec95
 - Input for CGI POST requests didn't work [Christian Huldt, I think].
 - Fixed various details in AppleEvent I/O streams, among them a very bad
   bug with remote control mode.
 - Removed edition manager support. I'm not sure if anyone was ever really
   using it, and apparently it caused problems on some machines. 
 - The long standing dependency on AppleScript should now a thing of the
   past [Too many people to thank].
 - Tried to improve sleep() behaviour [Paul Schinder].
 - STDERR was overly buffered [Brad Cox].
 - Copy & Paste had problems [Torsten Ekedahl].
 - Created macperl.{pod,html} from MacPerl.Specifics.
 - -w would give warnings about unused MacPerl::Version [Martin Heller].
 - Some versions of system were buggy [Charles Bailey].
 - Negative and big integers in MacPerl are very tricky. Fixed some bugs,
   would like to hear if there are any more [Steve Bollinger].
 - Verbose die()s would crash [Jon S. Stevens]
 
5.0.3r1m 26Nov95
 - When opening files, MacPerl 5.0.2r1m (and all earlier versions) calls
	PrValidate without calling PrOpen first. This causes horrible crashes
	when certain printers are selected, notably PDFWriter [Todd Hivnor].
 - I was locking the text handle of the front window "forever" as soon as 
   text was selected, which caused some operations to fail. This bug was
	also in MacPerl4, but never seems to have been found [Stonewall Ballard].
 - The MacPerl5 glue to choose() had a bug which caused PutFile to fail if a 
   default was specified [Espen S. Ore].
 - "-D" messages now go to the correct window, and you should no longer get
   bogus malloc diagnostics on startup of a script [Martin Heller].
 - Fixed an anachronism in perl5db.pl [Martin Heller].
 - Calling -v twice in a row would crash [Phil Ames].
 - Environment variables from the CGI glue would not be propagated correctly.
 - The XL callback glue had a bug which would lead to unpredictable
   results from XCMD calls [Jason Buberel].
 - A change introduced in 5.0.1 was causing input from the console to
   misbehave [Yuemo Zeng and Larry Allen-Tonar].

5.0.2r1m 05Nov95
 - Library paths got corrupted [Paul Schinder].
 - A bug in the help code led to crashes with System error 11 on startup 
 	[Charles Albrecht and Richard Moe]. 
 - After stopping a script with Command-., the next script would crash.
 - A few items omitted from the 5.0.1 notes:
 	- readlink() no longer mounts network volumes. This has the disadvantage
	  that you can't necessarily expect the result to be open()able, but is 
	  probably more useful for checking scripts [Martin Heller].
	- system now is implemented as print `xxx`, which is not quite correct
	  but covers the typical use of system().
	- umask is "implemented", but simply does nothing.
	- link is "implemented", but always fails.

5.0.1r1m	31Oct95
	I feel pretty good about this release:
	 -	Reliability should be considerably improved over 5.0.0
	 - The application features a new help system, based on suggestions by
	 	Martin Heller. You need to install Internet Config 1.2 and then 
		set up you favorite WWW browser as a helper entry for "file" for
		the whole thing to work.
	 - Thanks to persistent lobbying by Dick Karpinski, the application now
	   supports raw keyboard input. Check out :t:mac:Raw.t for an example.
	 - The script menu now has an entry for syntax checking the front window,
	   for turning on the debugger and for turning on compilation warnings.
		I believe that the new debugger interface will make it easier to debug
		droplets and such.
	 - The a2p tool has been included and sort of works. 
	 - A source code release should appear within a week.
	 
5.0.0		25Aug95
	This release is too good to delay and too bad to release. It had to go out
	today as I'm leaving for holidays. In general, it seems to behave sensibly,
	except for the application in out of memory situations. Don't run out of
	memory. The library is mostly untested. 
		Extra points for identifying all sounds in the about box and for finding 
	the one feature that is missing in MacPerl4, although it could theoretically 
	have been implemented there.