�cpan-mac-0.50.readme�������������������������������������������TEXT·uck��†K������8•��®²ÎT¡µæéA�����������������������†��=head1 NAME

cpan-mac - Tools for using CPAN with MacPerl (and other stuff)

=head1 SYNOPSIS

This package includes five programs. One droplet for creating tar.gz
archives (targzipme), one for unpacking them (untargzipme), one for
unpacking and installing, or just installing (installme), one
for accessing CPAN using the CPAN.pm module (CPAN-shell),
and one for installing all of the above, including the many modules
for supporting these programs (INSTALL).

NOTE: this package will NOT aid in the building of XS modules! If
you need to build distributions that you download, that contain
.xs or .c or other compilable files, please see Arved Sandstrom's
Mac XS tutorial.

http://macperl.com/depts/Tutorials/

Also NOTE: don't assume warnings are errors. They usually are not.
Feel free to send reports of your output if you do generate errors.

http://sourceforge.net/projects/cpan-mac/

One more NOTE: follow the directions in this file carefully, please.

=head1 DESCRIPTION

=head2 Requirements

=over 4

=item

PPC or CFM68K versions of the MacPerl distribution

=item

Roughly 10MB of RAM for targzipme and untargzipme

=item

Roughly 30MB of RAM for CPAN-shell

=back

=head2 Installation

Run the INSTALL.plx program. It will copy all the needed modules
and shared libraries to your F<:site_perl> directory, run autosplit
on the module files, and create directories as needed.

Then it will prompt for copying the droplets to the MacPerl folder
and creating aliases on the desktop. Finally, it will prompt the
user to increase the memory partition of the MacPerl application
to a suitable amount.

Then you will need to increase the partitions as necessary. It is
a very good idea to also B<go to your MacPerl preferences and put
your F<:site_perl> directory in the libraries list> specifically.
It should already be in the window, but you want it to come first,
so you need to add it in by hand.

For configuring CPAN.pm for the first time, see L<"CPAN-shell"> below.

=head1 CONTENTS

=head2 Programs

=over 4

=item targzipme

This droplet will create an archive from a folder, suitable for
unpacking with untargzipme.plx below. It is primarily for developers.
When launched, the developer has the opportunity to (1) make all
binary files MacBinarized and translate all text files from Mac to
Unix newlines, (2) do no conversion, or (3) bring up a window
containing the names of all files in the archive, allowing the
developer to select a mode for each file.

The modes in the window are text conversion (plain), MacBinary
conversion (bold), and no conversion (italic).

The droplet will also attempt to create a filename that will
fit within the Mac OS 31-character limit. It would be best
for the developer to first create a directory that fits within
27 characters, so ".tgz" can fit after the name.

The droplet will not create an archive if the archive already exists.

=item untargzipme

This droplet will unpack a .tar.gz (or .tgz) archive. If a Macbinary
file is found (a binary file ending in .bin), this droplet will
attempt to demacbinarize it, and if a text file is found, this droplet
will attempt to translate it from Unix or DOS newlines to Mac OS
newlines.

There is a secondary option on launch that can be chosen to do no
translation of any documents.

The droplet will not unpack an archive if the directory to unpack to
already exists.

=item installme

If a .tar.gz or .tgz archive is dropped on this droplet, it will first
unpack it, in the same way as untargzipme. After unpacking, it will
then install the contents of the newly created folder. If a folder is
dropped on the droplet instead of a .tar.gz or .tgz file, it will just
go ahead and install the contents of the folder.

It uses the same routines as CPAN.pm does for make and make install,
contained in ExtUtils::MM_MacOS. This is a nice alternative to
using CPAN.pm, if you have limited RAM, or if you happen to have a
specific distribution already downloaded.

B<NB:> if you use Stuffit Expander or somesuch to unpack the archive
and then use installme on the unpacked folder, you may have some
problems with newlines and MacBinary files. Many utilities will
not do newline conversion for you (though most will if you set it
to do so in the preferences), and few if any (aside from untarzipme)
will demacbinarize MacBinary files that are included in the archive.
It is usually safest to use untarzipme, or just go through and check
all the text and MacBinary (.bin) files by hand.

=item CPAN-shell

For information on how to use the CPAN shell, see the documentation
contained in the CPAN.pm file.

This requires quite a bit of RAM, as noted above. It also can run
slowly on older systems. My two test systems are a PowerBook G3/292
with 160MB of RAM and an iMac 233 with 96MB of RAM. So my systems
are decked out, and they work well. But with large distributions,
even mine with 40MB allocated to MacPerl can run out of memory. If
you get an out of memory error from MacPerl, quit the application.
If you try to run another script, you can crash your computer.

Before running it the first time, B<make sure that you have a HOME
variable set in your environment variables preferences in the MacPerl
application>. This can be anything. Most people use either their MacPerl
directory, or a working "user" directory, or the Preferences folder
inside the System Folder. Also, it might be a good idea to add an
EDITOR variable, which would be a four-character creator ID of your
favorite text editor.

When running the first time, select the defaults during configuration
unless you know what you are doing. For the B<pager> configuration,
you can put in the four-character creator ID of your favorite text
editor.

When you get to the MIRRORED.BY section, a file containing CPAN
mirrors will be downloaded to your computer, and you will be
prompted for where you live in the world, and then presented a
list of CPAN mirrors, where you will type in the numbers matching
the CPAN mirrors you want to use. B<For each of the questions in
this section, you will need to hit control-D to continue (you might
even have to hit it twice). You
can hit RETURN for the other questions in configuration.>

Once configuration is done, you can use the shell normally. Here
is a safe procedure that can be used to install most distributions.
Note that it is often better to install modules individually
rather than Bundles, unless you know a Bundle is safe to install
under MacPerl.

First, of course, you should check CPAN Testers to see if the module
has been tested for MacPerl (http://www.perl.org/cpan-testers/).

cpan> readme Some::Module # will open README file in your
# editor or "pager".

cpan> get Some::Module # will get the module
# distribution and unpack
# it similarly to
# untargzipme. inspect
# distribution to see if
# it needs to be compiled as XS,
# or if it is not compatible
# with MacPerl.

cpan> make Some::Module # will prepare module for
# installation; will NOT
# compile XS modules.

cpan> install Some::Module # installs module.

cpan> look Some::Module # will open the distribution's
# folder in the Finder
# (downloading distribution
# if necessary). run tests by
# hand.

The command C<test> does not test; it will C<get> and C<make> a
distribution, though. XS modules are not built. C<clean> does
nothing. Everything else pretty much works the same as it does
on Unix.

=back

=head2 Included Modules

Note that where there are parentheses after a name, that module
(or one or more files from that distribution) has been changed
from its form in the author's distribution.

Most of the module versions included here can be obtained from
CPAN. All exceptions have a * in front of the name. Binary
distributions and other ports can usually be found at MacPerl
Module Porters (http://pudge.net/mmp/).

Compress::Zlib, Digest::MD5, and Storable have not been updated
to their latest versions because I couldn't build them for various
reasons very easily, and there was no apparent need.

Archive::Tar was not updated because of a problem with
its use of Compress::Zlib.

HTML::Parser was not updated to the 3.x version, because I didn't
have a chance to test it, and it seems pretty much OK here. If
you want the 3.x version, which is based on XS, see the MMP site.

Archive::Tar 0.21 Stephen Zander
AutoLoader Fixed by Paul Schinder
* AutoSplit Fixed by Chris Nandor
Compress::Zlib 1.04 Paul Marquess (built by CN)
Convert::BinHex 1.119 Eryq
CPAN 1.57 Andreas Koenig
CPAN::WAIT 0.27 Ulrich Pfeifer
Data::Dumper 2.101 Gurusamy Sarathy (built by CN)
Digest::MD5 2.09 Gisle Aas (built by CN)
Exporter From perl5.004_05
ExtUtils::MM_MacOS Matthias Neeracher (CN)
File::Spec 0.82 Barrie Slaymaker
FreezeThaw 0.3 Ilya Zakharevich
HTML::Parser 2.23 Gisle Aas
LWP 5.48 Gisle Aas (PS) ???
libnet 1.0703 Graham Barr
* Mac::AppleEvents 1.22 Matthias Neeracher (CN)
Mac::AppleEvents::Simple 1.00 Chris Nandor
Mac::Apps::Launch 1.70 Chris Nandor
Mac::Conversions 1.03 Paul Schinder
Mac::FileSpec::Unixish 1.11 Sean Burke
* Mac::InternetConfig Matthias Neeracher (CN)
* Mac::Memory 1.20 Matthias Neeracher (CN)
* Mac::Processes 1.01 Matthias Neeracher (CN)
* Mac::Types Matthias Neeracher (CN)
MailTools 1.15 Graham Barr
MIME::Base64 2.11 Gisle Aas (built by CN)
MLDBM 2.00 Gurusamy Sarathy
Net::Telnet 3.02 Jay Rogers
Storable 0.604 Raphael Manfredi (built by CN)
URI 1.04 Gisle Aas

=head1 BUGS

=over 4

=item

Long filename distributions (more than 31 characters) are downloaded,
but if the folders in the tar archives are over 31 characters, then
unpacking will fail.

=item

Only .gz and .tar files are dealt with (which covers most
distributions).

=item

MacPerl might think a file or folder is busy, and you have to trash
it manually. This usually happens when something else "bad"
happens first.

=item

Complicated Makefile.PL files, or ones that otherwise fail because
of stuff that doesn't work under MacPerl, will cause the make
and install to be unable to complete.

=item

A best effort has been made to identify all the proper .pm files
to be installed in the right place. Please pay attention, though,
to files that are installed that should not be, or files that
are not installed that should be.

=item

The PREREQ_PM stuff is not honored right now.

=back

=head1 HISTORY

=over 4

=item v0.50 (14 September 2000)

Most modules updated to latest versions, with some noted exceptions.

Made macbinary detection more reliable using the C<is_macbinary()>
function from Mac::Conversions. (Paul Schinder)

=item v0.40 (01 September 1999)

Use IC prefs to set file and creator types from file suffix. Files of
unknown type are set to TEXT, with the creator as the type of the
C<editor> helper app (or C<ttxt>).

Really fixed Types warning. I think.

Made C<$verbose = 1> where before it was C<0>. Let me know if there
are some things it doesn't say which you'd rather it would.

Fixed unpacking to not die if a file is not found (usually because : was
in the filename or it was > 31 characters).

Compress::Zlib had the current (1.04) binaries, but the older (1.01)
module file. Fixed.

Added Mac::FileSpec::Unixish to ExtUtils::MM_MacOS to help convert
filenames properly. It is not required, but macify() works better
if it is.

Added MailTools to do mail for perlbug.

Added new versions of Mac::AppleEvents::Simple, URI, Mac::Conversions,
Storable, Digest::MD5.

=item v0.32 (09 July 1999)

Fixed INSTALL bugs, Types warning, and CPAN-shell bug.

=item v0.31 (08 July 1999)

Fixed install problem with bad AutoSplit.

=item v0.30 (08 July 1999)

Updated modules a bunch of modules. Added AutoSplit, Mac::Memory,
Mac::AppleEvents, Mac::InternetConfig, Mac::Types, Storable, MLDBM,
FreezeThaw.

Did some cleanup.

=item v0.22 (28 January 1999)

=over 4

=item

Added support for CPAN's look function.

=item

Fixed a small bug in the InstallBLIB code that did not have a C</g> on
the C<s/::/:/> code (Paul Schinder).

=item

If cpan-mac-0.21 is already installed, just copy F<CPAN.pm> and
F<ExtUtils/MM_MacOS.pm> by hand to your F<site_perl> directory.

=back

=item v0.21 (25 January 1999)

=over 4

=item

Re-upload.

=back

=item v0.20 (25 January 1999)

=over 4

=item

First public release.

=item

Changes to docs (Paul Schinder).

=item

Update CPAN.pm to version 1.47.

=item

Added installme program and documentation.

=item

(Hopefully) fixed problem with ExtUtils::MM_MacOS::make() not
running Makefile.PL (Larry Moore).

=back

=item v0.10 (23 January 1999)

=over 4

=item

First release of entire package.

=item

Patches for CPAN 1.45 and CPAN::FirstTime submitted to Andreas Koenig.

=back

=head1 THANKS

Thanks to lots of people, most recently Paul Corr, Peter Prymmer, and
Georg Bauer.

=head1 AUTHOR

Above modules are authored by different people and are subject to
separate copyrights. Copyright below only regards distribution and
included programs installme, targzipme, untargzipme, INSTALL.

Chris Nandor E<lt>pudge@pobox.comE<gt>, http://pudge.net/

=head1 SEE ALSO

http://sourceforge.net/projects/cpan-mac/
http://pudge.net/mmp/
http://www.cpan.org/

=head1 VERSION

Version 0.50 (14 September 2000)
����������������������������������������������������������������������������������������������������������������h��h���FúPPOp�`,/.�/
R h�$NPO&@ f-øbgB§/<ÿÿóÊNºú"PO Lß�N^NuNV��/
Nº�p$@
gHn�/
R h�,NPO$_N^NuNV��/
/.� mñ$h�/
R h�ˆNPO$_N^NuNV��/
/.� mñ$h�/
R h�ŒNPO$_N^Nu -ñNuB@Nu mñ (�(NuNV��/.�NºþØN^ _XONÐNV��B§/.�NºþèN^ _XONÐHç00-ød���H� ProFont����������������������������G3Õ³�G3Õ³µæéA��8•��8•��4¦���R*ch�‚�������������������������������������������������������������������������������������������������������������������������Courier���������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������
��� Helvetica������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Confidential���������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������€���€���€���€�����������P���������������������������������������������������������������������������������������������������������h��h���F
ý“˜¦����F�MPSR���BBST���íÿÿ����TH�€ÿÿ���LMg ����������������������������������������������������������������������������������