major pod update from Tom Christiansen

p4raw-id: //depot/perl@3460

1 files changed, 404 insertions, 146 deletions

diff --git a/pod/perlmodlib.pod b/pod/perlmodlib.pod
index 2dc38dfd80..4cee4556b6 100644
--- a/pod/perlmodlib.pod
+++ b/pod/perlmodlib.pod
@@ -6,54 +6,76 @@ perlmodlib - constructing new Perl modules and finding existing ones
 
 =head1 THE PERL MODULE LIBRARY
 
-A number of modules are included the Perl distribution.  These are
-described below, and all end in F<.pm>.  You may also discover files in
-the library directory that end in either F<.pl> or F<.ph>.  These are old
-libraries supplied so that old programs that use them still run.  The
-F<.pl> files will all eventually be converted into standard modules, and
-the F<.ph> files made by B<h2ph> will probably end up as extension modules
-made by B<h2xs>.  (Some F<.ph> values may already be available through the
-POSIX module.)  The B<pl2pm> file in the distribution may help in your
-conversion, but it's just a mechanical process and therefore far from
-bulletproof.
+Many modules are included the Perl distribution.  These are described
+below, and all end in F<.pm>.  You may discover compiled library
+file (usually ending in F<.so>) or small pieces of modules to be
+autoloaded (ending in F<.al>); these were automatically generated
+by the installation process.  You may also discover files in the
+library directory that end in either F<.pl> or F<.ph>.  These are
+old libraries supplied so that old programs that use them still
+run.  The F<.pl> files will all eventually be converted into standard
+modules, and the F<.ph> files made by B<h2ph> will probably end up
+as extension modules made by B<h2xs>.  (Some F<.ph> values may
+already be available through the POSIX, Errno, or Fcntl modules.)
+The B<pl2pm> file in the distribution may help in your conversion,
+but it's just a mechanical process and therefore far from bulletproof.
 
 =head2 Pragmatic Modules
 
-They work somewhat like pragmas in that they tend to affect the compilation of
-your program, and thus will usually work well only when used within a
-C<use>, or C<no>.  Most of these are lexically scoped, so an inner BLOCK
-may countermand any of these by saying:
+They work somewhat like compiler directives (pragmata) in that they
+tend to affect the compilation of your program, and thus will usually
+work well only when used within a C<use>, or C<no>.  Most of these
+are lexically scoped, so an inner BLOCK may countermand them
+by saying:
 
     no integer;
     no strict 'refs';
 
 which lasts until the end of that BLOCK.
 
-Unlike the pragmas that effect the C<$^H> hints variable, the C<use
-vars> and C<use subs> declarations are not BLOCK-scoped.  They allow
-you to predeclare a variables or subroutines within a particular
-I<file> rather than just a block.  Such declarations are effective
-for the entire file for which they were declared.  You cannot rescind
-them with C<no vars> or C<no subs>.
+Some pragmas are lexically scoped--typically those that affect the
+C<$^H> hints variable.  Others affect the current package instead,
+like C<use vars> and C<use subs>, whic allow you to predeclare a
+variables or subroutines within a particular I<file> rather than
+just a block.  Such declarations are effective for the entire file
+for which they were declared.  You cannot rescind them with C<no
+vars> or C<no subs>.
 
 The following pragmas are defined (and have their own documentation).
 
 =over 12
 
-=item use autouse MODULE => qw(sub1 sub2 sub3)
+=item attrs
 
-Defers C<require MODULE> until someone calls one of the specified
-subroutines (which must be exported by MODULE).  This pragma should be
-used with caution, and only when necessary.
+set/get attributes of a subroutine
+
+=item autouse
+
+postpone load of modules until a function is used
+
+=item base
+
+Establish IS-A relationship with base class at compile time
 
 =item blib
 
-manipulate @INC at compile time to use MakeMaker's uninstalled version
-of a package
+Use MakeMaker's uninstalled version of a package
+
+=item constant
+
+declare constants
 
 =item diagnostics
 
-force verbose warning diagnostics
+Perl compiler pragma to force verbose warning diagnostics
+
+=item fields
+
+compile-time class fields
+
+=item filetest
+
+control the filetest permission operators
 
 =item integer
 
@@ -61,7 +83,7 @@ compute arithmetic in integer instead of double
 
 =item less
 
-request less of something from the compiler
+perl pragma to request less of something from the compiler
 
 =item lib
 
@@ -69,19 +91,19 @@ manipulate @INC at compile time
 
 =item locale
 
-use or ignore current locale for builtin operations (see L<perllocale>)
+use and avoid POSIX locales for built-in operations
 
 =item ops
 
-restrict named opcodes when compiling or running Perl code
+restrict unsafe operations when compiling
 
 =item overload
 
-overload basic Perl operations
+Package for overloading perl operations
 
 =item re
 
-alter behaviour of regular expressions
+alter regular expression behavior
 
 =item sigtrap
 
@@ -95,14 +117,22 @@ restrict unsafe constructs
 
 predeclare sub names
 
-=item vmsish
+=item utf8
 
-adopt certain VMS-specific behaviors
+turn on UTF-8 and Unicode support
 
 =item vars
 
 predeclare global variable names
 
+=item vmsish
+
+control VMS-specific language features
+
+=item warning
+
+control optional warnings
+
 =back
 
 =head2 Standard Modules
@@ -119,27 +149,115 @@ provide framework for multiple DBMs
 
 =item AutoLoader
 
-load functions only on demand
+load subroutines only on demand
 
 =item AutoSplit
 
 split a package for autoloading
 
+=item B
+
+The Perl Compiler; See also L<perlcc>.
+
+=item B::Asmdata
+
+Autogenerated data about Perl ops, used to generate bytecode
+
+=item B::Assembler
+
+Assemble Perl bytecode
+
+=item B::Bblock
+
+Walk basic blocks
+
+=item B::Bytecode
+
+Perl compiler's bytecode backend
+
+=item B::C
+
+Perl compiler's C backend
+
+=item B::CC
+
+Perl compiler's optimized C translation backend
+
+=item B::Debug
+
+Walk Perl syntax tree, printing debug info about ops
+
+=item B::Deparse
+
+Perl compiler backend to produce perl code
+
+=item B::Disassembler
+
+Disassemble Perl bytecode
+
+=item B::Lint
+
+Perl lint
+
+=item B::Showlex
+
+Show lexical variables used in functions or files
+
+=item B::Stackobj
+
+Helper module for CC backend
+
+=item B::Terse
+
+Walk Perl syntax tree, printing terse info about ops
+
+=item B::Xref
+
+Generates cross reference reports for Perl programs
+
 =item Benchmark
 
 benchmark running times of code
 
+=item CGI
+
+Simple Common Gateway Interface Class
+
+=item CGI::Apache
+
+Make things work with CGI.pm against Perl-Apache API
+
+=item CGI::Carp
+
+CGI routines for writing to the HTTPD (or other) error log
+
+=item CGI::Cookie
+
+Interface to Netscape Cookies
+
+=item CGI::Fast
+
+CGI Interface for Fast CGI
+
+=item CGI::Push
+
+Simple Interface to Server Push
+
+=item CGI::Switch
+
+Try more than one constructors and return the first object available
+
 =item CPAN
 
-interface to Comprehensive Perl Archive Network
+query, download and build perl modules from CPAN sites
 
 =item CPAN::FirstTime
 
-create a CPAN configuration file
+Utility for CPAN::Config file Initialization
 
 =item CPAN::Nox
 
-run CPAN while avoiding compiled extensions
+Wrapper around CPAN.pm without using any XS module
 
 =item Carp
 
@@ -147,7 +265,7 @@ warn of errors (from perspective of caller)
 
 =item Class::Struct
 
-declare struct-like datatypes
+declare struct-like datatypes as Perl classes
 
 =item Config
 
@@ -157,13 +275,21 @@ access Perl configuration information
 
 get pathname of current working directory
 
+=item DB
+
+programmatic interface to the Perl debugging API 
+
 =item DB_File
 
-access to Berkeley DB
+Perl5 access to Berkeley DB version 1.x
+
+=item Data::Dumper
+
+stringified perl data structures, suitable for both printing and C<eval>
 
 =item Devel::Peek
 
-data debugging tool for the XS programmer
+A data debugging tool for the XS programmer
 
 =item Devel::SelfStubber
 
@@ -173,9 +299,13 @@ generate stubs for a SelfLoading module
 
 supply object methods for directory handles
 
+=item Dumpvalue
+
+provides screen dump of Perl data.
+
 =item DynaLoader
 
-dynamically load C libraries into Perl code
+Dynamically load C libraries into Perl code
 
 =item English
 
@@ -183,27 +313,39 @@ use nice English (or awk) names for ugly punctuation variables
 
 =item Env
 
-import environment variables
+perl module that imports environment variables
+
+=item Errno
+
+System errno constants
 
 =item Exporter
 
-implements default import method for modules
+Implements default import method for modules
+
+=item ExtUtils::Command
+
+utilities to replace common UNIX commands in Makefiles etc.
 
 =item ExtUtils::Embed
 
-utilities for embedding Perl in C/C++ applications
+Utilities for embedding Perl in C/C++ applications
 
 =item ExtUtils::Install
 
 install files from here to there
 
+=item ExtUtils::Installed
+
+Inventory management of installed modules
+
 =item ExtUtils::Liblist
 
 determine libraries to use and how to use them
 
 =item ExtUtils::MM_OS2
 
-methods to override Unix behaviour in ExtUtils::MakeMaker
+methods to override UN*X behavior in ExtUtils::MakeMaker
 
 =item ExtUtils::MM_Unix
 
@@ -211,7 +353,11 @@ methods used by ExtUtils::MakeMaker
 
 =item ExtUtils::MM_VMS
 
-methods to override Unix behaviour in ExtUtils::MakeMaker
+methods to override UN*X behavior in ExtUtils::MakeMaker
+
+=item ExtUtils::MM_Win32
+
+methods to override UN*X behavior in ExtUtils::MakeMaker
 
 =item ExtUtils::MakeMaker
 
@@ -221,6 +367,10 @@ create an extension Makefile
 
 utilities to write and check a MANIFEST file
 
+=item ExtUtils::Miniperl
+
+write the C code for perlmain.c
+
 =item ExtUtils::Mkbootstrap
 
 make a bootstrap file for use by DynaLoader
@@ -229,13 +379,17 @@ make a bootstrap file for use by DynaLoader
 
 write linker options files for dynamic extension
 
+=item ExtUtils::Packlist
+
+manage .packlist files
+
 =item ExtUtils::testlib
 
 add blib/* directories to @INC
 
 =item Fatal
 
-make errors in builtins or Perl functions fatal
+replace functions with equivalents which succeed or die
 
 =item Fcntl
 
@@ -245,17 +399,17 @@ load the C Fcntl.h defines
 
 split a pathname into pieces
 
-=item File::CheckTree
-
-run many filetest checks on a tree
-
 =item File::Compare
 
-compare files or filehandles
+Compare files or filehandles
 
 =item File::Copy
 
-copy files or filehandles
+Copy files or filehandles
+
+=item File::DosGlob
+
+DOS like globbing and then some
 
 =item File::Find
 
@@ -271,11 +425,31 @@ portably perform operations on file names
 
 =item File::Spec::Functions
 
-function call interface to File::Spec module
+portably perform operations on file names
+
+=item File::Spec::Mac
+
+File::Spec for MacOS
+
+=item File::Spec::OS2
+
+methods for OS/2 file specs
+
+=item File::Spec::Unix
+
+methods used by File::Spec
+
+=item File::Spec::VMS
+
+methods for VMS file specs
+
+=item File::Spec::Win32
+
+methods for Win32 file specs
 
 =item File::stat
 
-by-name interface to Perl's builtin stat() functions
+by-name interface to Perl's built-in stat() functions
 
 =item FileCache
 
@@ -287,11 +461,11 @@ supply object methods for filehandles
 
 =item FindBin
 
-locate directory of original Perl script
+Locate directory of original perl script
 
 =item GDBM_File
 
-access to the gdbm library
+Perl5 access to the gdbm library.
 
 =item Getopt::Long
 
@@ -299,7 +473,7 @@ extended processing of command line options
 
 =item Getopt::Std
 
-process single-character switches with switch clustering
+Process single-character switches with switch clustering
 
 =item I18N::Collate
 
@@ -309,6 +483,10 @@ compare 8-bit scalar data according to the current locale
 
 load various IO modules
 
+=item IO::Dir
+
+supply object methods for directory handles
+
 =item IO::File
 
 supply object methods for filehandles
@@ -321,6 +499,10 @@ supply object methods for I/O handles
 
 supply object methods for pipes
 
+=item IO::Poll
+
+Object interface to system poll call
+
 =item IO::Seekable
 
 supply seek based methods for I/O objects
@@ -331,7 +513,19 @@ OO interface to the select system call
 
 =item IO::Socket
 
-object interface to socket communications
+Object interface to socket communications
+
+=item IO::Socket::INET
+
+Object interface for AF_INET domain sockets
+
+=item IO::Socket::UNIX
+
+Object interface for AF_UNIX domain sockets
+
+=item IPC::Msg
+
+SysV Msg IPC object class
 
 =item IPC::Open2
 
@@ -341,13 +535,21 @@ open a process for both reading and writing
 
 open a process for reading, writing, and error handling
 
+=item IPC::Semaphore
+
+SysV Semaphore IPC object class
+
+=item IPC::SysV
+
+SysV IPC constants
+
 =item Math::BigFloat
 
-arbitrary length float math package
+Arbitrary length float math package
 
 =item Math::BigInt
 
-arbitrary size integer math package
+Arbitrary size integer math package
 
 =item Math::Complex
 
@@ -355,52 +557,59 @@ complex numbers and associated mathematical functions
 
 =item Math::Trig
 
-simple interface to parts of Math::Complex for those who
-need trigonometric functions only for real numbers
+trigonometric functions
 
 =item NDBM_File
 
-tied access to ndbm files
+Tied access to ndbm files
 
 =item Net::Ping
 
-Hello, anybody home?
+check a remote host for reachability
 
 =item Net::hostent
 
-by-name interface to Perl's builtin gethost*() functions
+by-name interface to Perl's built-in gethost*() functions
 
 =item Net::netent
 
-by-name interface to Perl's builtin getnet*() functions
+by-name interface to Perl's built-in getnet*() functions
 
 =item Net::protoent
 
-by-name interface to Perl's builtin getproto*() functions
+by-name interface to Perl's built-in getproto*() functions
 
 =item Net::servent
 
-by-name interface to Perl's builtin getserv*() functions
+by-name interface to Perl's built-in getserv*() functions
 
-=item Opcode
+=item O
 
-disable named opcodes when compiling or running Perl code
+Generic interface to Perl Compiler backends
 
-=item Pod::Text
+=item Opcode
 
-convert POD data to formatted ASCII text
+Disable named opcodes when compiling perl code
 
 =item POSIX
 
-interface to IEEE Standard 1003.1
+Perl interface to IEEE Std 1003.1
+
+=item Pod::Html
+
+module to convert pod files to HTML
+
+=item Pod::Text
+
+convert POD data to formatted ASCII text
 
 =item SDBM_File
 
-tied access to sdbm files
+Tied access to sdbm files
 
 =item Safe
 
-compile and execute code in restricted compartments
+Compile and execute code in restricted compartments
 
 =item Search::Dict
 
@@ -416,7 +625,7 @@ load functions only on demand
 
 =item Shell
 
-run shell commands transparently within Perl
+run shell commands transparently within perl
 
 =item Socket
 
@@ -428,27 +637,31 @@ manipulate Perl symbols and their names
 
 =item Sys::Hostname
 
-try every conceivable way to get hostname
+Try every conceivable way to get hostname
 
 =item Sys::Syslog
 
-interface to the Unix syslog(3) calls
+Perl interface to the UNIX syslog(3) calls
 
 =item Term::Cap
 
-termcap interface
+Perl termcap interface
 
 =item Term::Complete
 
-word completion module
+Perl word completion module
 
 =item Term::ReadLine
 
-interface to various C<readline> packages
+Perl interface to various C<readline> packages. 
+
+=item Test
+
+provides a simple framework for writing test scripts
 
 =item Test::Harness
 
-run Perl standard test scripts with statistics
+run perl standard test scripts with statistics
 
 =item Text::Abbrev
 
@@ -456,35 +669,61 @@ create an abbreviation table from a list
 
 =item Text::ParseWords
 
-parse text into an array of tokens
+parse text into an array of tokens or array of arrays
 
 =item Text::Soundex
 
-implementation of the Soundex Algorithm as described by Knuth
-
-=item Text::Tabs
+Implementation of the Soundex Algorithm as Described by Knuth
 
-expand and unexpand tabs per the Unix expand(1) and unexpand(1)
+=item Text::Tabs -- expand and unexpand tabs per the unix expand(1) and unexpand(1)
 
 =item Text::Wrap
 
 line wrapping to form simple paragraphs
 
-=item Tie::Hash
+=item Thread 
+
+multithreading
+
+=item Thread::Queue 
+
+thread-safe queues
+
+=item Thread::Semaphore 
+
+thread-safe semaphores
+
+=item Thread::Signal 
+
+Start a thread which runs signal handlers reliably
+
+=item Thread::Specific 
+
+thread-specific keys
+
+=item Tie::Array
+
+base class for tied arrays
+
+=item Tie::Handle
+
+base class definitions for tied handles
+
+=item Tie::Hash, Tie::StdHash
 
 base class definitions for tied hashes
 
 =item Tie::RefHash
 
-base class definitions for tied hashes with references as keys
+use references as hash keys
 
-=item Tie::Scalar
+=item Tie::Scalar, Tie::StdScalar
 
 base class definitions for tied scalars
 
 =item Tie::SubstrHash
 
-fixed-table-size, fixed-key-length hashing
+Fixed-table-size, fixed-key-length hashing
 
 =item Time::Local
 
@@ -492,11 +731,11 @@ efficiently compute time from local and GMT time
 
 =item Time::gmtime
 
-by-name interface to Perl's builtin gmtime() function
+by-name interface to Perl's built-in gmtime() function
 
 =item Time::localtime
 
-by-name interface to Perl's builtin localtime() function
+by-name interface to Perl's built-in localtime() function
 
 =item Time::tm
 
@@ -508,42 +747,54 @@ base class for ALL classes (blessed references)
 
 =item User::grent
 
-by-name interface to Perl's builtin getgr*() functions
+by-name interface to Perl's built-in getgr*() functions
 
 =item User::pwent
 
-by-name interface to Perl's builtin getpw*() functions
+by-name interface to Perl's built-in getpw*() functions
 
 =back
 
-To find out I<all> the modules installed on your system, including
-those without documentation or outside the standard release, do this:
+To find out I<all> modules installed on your system, including
+those without documentation or outside the standard release, 
+jus tdo this:
 
     % find `perl -e 'print "@INC"'` -name '*.pm' -print
 
-They should all have their own documentation installed and accessible via
-your system man(1) command.  If that fails, try the I<perldoc> program.
+They should all have their own documentation installed and accessible
+via your system man(1) command.  If you do not have a B<find>
+program, you can use the Perl B<find2perl> program instead, which
+generates Perl code as output you can run through perl.  If you
+have a B<man> program but it doesn't find your modules, you'll have
+to fix your manpath.  See L<perl> for details.  If you have no
+system B<man> command, you might try the B<perldoc> program.
 
 =head2 Extension Modules
 
-Extension modules are written in C (or a mix of Perl and C) and may be
-statically linked or in general are
-dynamically loaded into Perl if and when you need them.  Supported
-extension modules include the Socket, Fcntl, and POSIX modules.
+Extension modules are written in C (or a mix of Perl and C).  They
+are usually dynamically loaded into Perl if and when you need them,
+but may also be be linked in statically.  Supported extension modules
+include Socket, Fcntl, and POSIX.
 
 Many popular C extension modules do not come bundled (at least, not
-completely) due to their sizes, volatility, or simply lack of time for
-adequate testing and configuration across the multitude of platforms on
-which Perl was beta-tested.  You are encouraged to look for them in
-archie(1L), the Perl FAQ or Meta-FAQ, the WWW page, and even with their
-authors before randomly posting asking for their present condition and
-disposition.
+completely) due to their sizes, volatility, or simply lack of time
+for adequate testing and configuration across the multitude of
+platforms on which Perl was beta-tested.  You are encouraged to
+look for them on CPAN (described below), or using web search engines
+like Alta Vista or Deja News.
 
 =head1 CPAN
 
-CPAN stands for the Comprehensive Perl Archive Network.  This is a globally
-replicated collection of all known Perl materials, including hundreds
-of unbundled modules.  Here are the major categories of modules:
+CPAN stands for Comprehensive Perl Archive Network; it's a globally
+replicated trove of Perl materials, including documentation, style
+guides, tricks and trap, alternate ports to non-Unix systems and
+occasional binary distributions for these.   Search engines for
+CPAN can be found at http://cpan.perl.com/ and at
+http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
+
+Most importantly, CPAN includes around a thousand unbundled modules,
+some of which require a C compiler to build.  Major categories of
+modules are:
 
 =over
 
@@ -612,21 +863,18 @@ Miscellaneous Modules
 
 =back
 
-The registered CPAN sites as of this writing include the following.
+Registered CPAN sites as of this writing include the following.
 You should try to choose one close to you:
 
 =over
 
-=item *
-Africa
+=item Africa
 
    South Africa    ftp://ftp.is.co.za/programming/perl/CPAN/
                    ftp://ftpza.co.za/pub/mirrors/cpan/
 
-=item *
-Asia
+=item Asia
 
-   Armenia         ftp://sunsite.aua.am/pub/CPAN/
    China           ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
    Hong Kong       ftp://ftp.hkstar.com/pub/CPAN/
    Israel          ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
@@ -634,6 +882,7 @@ Asia
                    ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
                    ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
                    ftp://ftp.meisei-u.ac.jp/pub/CPAN/
+                   ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
                    ftp://mirror.nucba.ac.jp/mirror/Perl/
    Singapore       ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
    South Korea     ftp://ftp.bora.net/pub/CPAN/
@@ -643,8 +892,7 @@ Asia
    Thailand        ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
                    ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
 
-=item *
-Australasia
+=item Australasia
 
    Australia       ftp://cpan.topend.com.au/pub/CPAN/
                    ftp://ftp.labyrinth.net.au/pub/perl/CPAN/
@@ -653,13 +901,11 @@ Australasia
    New Zealand     ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
                    ftp://sunsite.net.nz/pub/languages/perl/CPAN/
 
-=item *
 Central America
 
    Costa Rica      ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
 
-=item *
-Europe
+=item Europe
 
    Austria         ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
    Belgium         ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
@@ -686,8 +932,10 @@ Europe
    Ireland         ftp://sunsite.compapp.dcu.ie/pub/perl/
    Italy           ftp://cis.uniRoma2.it/CPAN/
                    ftp://ftp.flashnet.it/pub/CPAN/
+                   ftp://ftp.unina.it/pub/Other/CPAN/
                    ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
    Netherlands     ftp://ftp.cs.uu.nl/mirror/CPAN/
+                   ftp://ftp.EU.net/packages/cpan/
                    ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
    Norway          ftp://ftp.uit.no/pub/languages/perl/cpan/
                    ftp://sunsite.uio.no/pub/languages/perl/CPAN/
@@ -696,10 +944,11 @@ Europe
                    ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
                    ftp://sunsite.icm.edu.pl/pub/CPAN/
    Portugal        ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/
+                   ftp://ftp.ist.utl.pt/pub/CPAN/
                    ftp://ftp.ua.pt/pub/CPAN/
    Romania         ftp://ftp.dntis.ro/pub/mirrors/perl-cpan/
                    ftp://ftp.dnttm.ro/pub/CPAN/
-   Russia          ftp://cpan.npi.msu.su/CPAN/
+    Russia         ftp://ftp.chg.ru/pub/lang/perl/CPAN/
                    ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
    Slovakia        ftp://ftp.entry.sk/pub/languages/perl/CPAN/
    Slovenia        ftp://ftp.arnes.si/software/perl/CPAN/
@@ -714,11 +963,11 @@ Europe
                    ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
                    ftp://unix.hensa.ac.uk/mirrors/perl-CPAN/
 
-=item *
-North America
+=item North America
 
    Alberta         ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
-   California      ftp://ftp.cdrom.com/pub/perl/CPAN/
+    California     ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
+                   ftp://ftp.cdrom.com/pub/perl/CPAN/
                    ftp://ftp.digital.com/pub/plan/perl/CPAN/
    Colorado        ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
    Florida         ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
@@ -728,30 +977,30 @@ North America
    Manitoba        ftp://theory.uwinnipeg.ca/pub/CPAN/
    Massachusetts   ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
                    ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
-   Mexico D.F.     ftp://ftp.msg.com.mx/pub/CPAN/
+    Mexico         ftp://ftp.msg.com.mx/pub/CPAN/
+    Minnesota      ftp://ftp.midearthbbs.com/CPAN/
    New York        ftp://ftp.rge.com/pub/languages/perl/
    North Carolina  ftp://ftp.duke.edu/pub/perl/
    Oklahoma        ftp://ftp.ou.edu/mirrors/CPAN/
-   Ontario         ftp://ftp.crc.ca/pub/packages/perl/CPAN/
+    Ontario        ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
    Oregon          ftp://ftp.orst.edu/pub/packages/CPAN/
    Pennsylvania    ftp://ftp.epix.net/pub/languages/perl/
    Texas           ftp://ftp.sedl.org/pub/mirrors/CPAN/
    Utah            ftp://mirror.xmission.com/CPAN/
    Virginia        ftp://ftp.perl.org/pub/perl/CPAN/
                    ftp://ruff.cs.jmu.edu/pub/CPAN/
-   Washington      ftp://ftp.spu.edu/pub/CPAN/
+    Washington     ftp://ftp-mirror.internap.com/pub/CPAN/
+                   ftp://ftp.spu.edu/pub/CPAN/
 
-=item *
-South America
+=item South America
 
    Brazil          ftp://cpan.if.usp.br/pub/mirror/CPAN/
-   Chile           ftp://ftp.ing.puc.cl/pub/unix/perl/CPAN/
-                   ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/
+    Chile          ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/
 
 =back
 
 For an up-to-date listing of CPAN sites,
-see F<http://www.perl.com/perl/CPAN> or F<ftp://ftp.perl.com/perl/>.
+see http://www.perl.com/perl/CPAN or ftp://www.perl.com/perl/ .
 
 =head1 Modules: Creation, Use, and Abuse
 
@@ -795,6 +1044,8 @@ scheme as the original author.
 
 =item Try to design the new module to be easy to extend and reuse.
 
+Always use B<-w>.  
+
 Use blessed references.  Use the two argument form of bless to bless
 into the class name given as the first parameter of the constructor,
 e.g.,:
@@ -819,7 +1070,7 @@ appropriate.  Split large methods into smaller more flexible ones.
 Inherit methods from other modules if appropriate.
 
 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
-Generally you can delete the "C<eq 'FOO'>" part with no harm at all.
+Generally you can delete the C<eq 'FOO'> part with no harm at all.
 Let the objects look after themselves! Generally, avoid hard-wired
 class names as far as possible.
 
@@ -833,7 +1084,7 @@ the module after __END__ either using AutoSplit or by saying:
  eval join('',<main::DATA>) || die $@ unless caller();
 
 Does your module pass the 'empty subclass' test? If you say
-"C<@SUBCLASS::ISA = qw(YOURCLASS);>" your applications should be able
+C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
 to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
 does your application still work if you change:  C<$obj = new YOURCLASS;>
 into: C<$obj = new SUBCLASS;> ?
@@ -842,11 +1093,18 @@ Avoid keeping any state information in your packages. It makes it
 difficult for multiple other packages to use yours. Keep state
 information in objects.
 
-Always use B<-w>. Try to C<use strict;> (or C<use strict qw(...);>).
+Always use B<-w>.  
+
+Try to C<use strict;> (or C<use strict qw(...);>).
 Remember that you can add C<no strict qw(...);> to individual blocks
-of code that need less strictness. Always use B<-w>. Always use B<-w>!
+of code that need less strictness.  
+
+Always use B<-w>.  
+
 Follow the guidelines in the perlstyle(1) manual.
 
+Always use B<-w>.
+
 =item Some simple style guidelines
 
 The perlstyle manual supplied with Perl has many helpful points.
@@ -1016,7 +1274,7 @@ should store your module's version number in a non-my package
 variable called $VERSION.  This should be a floating point
 number with at least two digits after the decimal (i.e., hundredths,
 e.g, C<$VERSION = "0.01">).  Don't use a "1.3.2" style version.
-See Exporter.pm in Perl5.001m or later for details.
+See L<Exporter> for details.
 
 It may be handy to add a function or method to retrieve the number.
 Use the number in announcements and archive file names when
@@ -1030,7 +1288,7 @@ module (or the module itself if small) to the comp.lang.perl.announce
 Usenet newsgroup.  This will at least ensure very wide once-off
 distribution.
 
-If possible you should place the module into a major ftp archive and
+If possible, register the module with CPAN.  You should 
 include details of its location in your announcement.
 
 Some notes about ftp archives: Please use a long descriptive file
@@ -1065,7 +1323,7 @@ Please remember to send me an updated entry for the Module list!
 
 Always strive to remain compatible with previous released versions.
 Otherwise try to add a mechanism to revert to the
-old behaviour if people rely on it. Document incompatible changes.
+old behavior if people rely on it.  Document incompatible changes.
 
 =back
 
@@ -1091,8 +1349,8 @@ it worth it unless you plan to make other changes at the same time?
 =item Make the most of the opportunity.
 
 If you are going to convert the script to a module you can use the
-opportunity to redesign the interface. The 'Guidelines for Module
-Creation' above include many of the issues you should consider.
+opportunity to redesign the interface.  The guidelines for module
+creation above include many of the issues you should consider.
 
 =item The pl2pm utility will get you started.