This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
doubled words in pods (from Simon Cozens
[perl5.git] / pod / perlmodlib.pod
index 05570d9..164cb64 100644 (file)
@@ -802,23 +802,28 @@ By-name interface to Perl's built-in getpw*() functions
 
 To find out I<all> modules installed on your system, including
 those without documentation or outside the standard release, 
-jus tdo this:
+jusdo 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 you do not have a B<find>
+To get a log of all module distributions which have been installed
+since perl was installed, just do:
+
+    % perldoc perllocal
+
+Modules should all have their own documentation installed and accessible
+via your system man(1) command, or via the C<perldoc> program.  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.
+to fix your manpath.  See L<perl> for details.
 
 =head2 Extension 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
+but may also be linked in statically.  Supported extension modules
 include Socket, Fcntl, and POSIX.
 
 Many popular C extension modules do not come bundled (at least, not
@@ -920,11 +925,11 @@ You should try to choose one close to you:
                    ftp://ftp.sun.ac.za/CPAN/
                    ftp://ftpza.co.za/pub/mirrors/cpan/
 
+
 =item Asia
 
     China          ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
-    Hong Kong      ftp://ftp.hkstar.com/pub/CPAN/
-                   ftp://ftp.pacific.net.hk/pub/mirror/CPAN/
+    Hong Kong      ftp://ftp.pacific.net.hk/pub/mirror/CPAN/
     Indonesia      ftp://malone.piksi.itb.ac.id/pub/CPAN/
     Israel         ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
     Japan          ftp://ftp.dti.ad.jp/pub/lang/CPAN/
@@ -933,30 +938,32 @@ You should try to choose one close to you:
                    ftp://ftp.meisei-u.ac.jp/pub/CPAN/
                    ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
                    ftp://mirror.nucba.ac.jp/mirror/Perl/
+    Saudi-Arabia   ftp://ftp.isu.net.sa/pub/CPAN/
     Singapore      ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
     South Korea    ftp://ftp.bora.net/pub/CPAN/
                    ftp://ftp.kornet.net/pub/CPAN/
                    ftp://ftp.nuri.net/pub/CPAN/
     Taiwan         ftp://coda.nctu.edu.tw/computer-languages/perl/CPAN/
                    ftp://ftp.ee.ncku.edu.tw/pub3/perl/CPAN/
-                   ftp://ftp.wownet.net/pub2/PERL/
                    ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
-    Thailand       ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
-                   ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
+    Thailand       ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
+
 
 =item Australasia
 
     Australia      ftp://cpan.topend.com.au/pub/CPAN/
-                   ftp://ftp.labyrinth.net.au/pub/perl/CPAN/
+                   ftp://ftp.labyrinth.net.au/pub/perl-CPAN/
                    ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/
                    ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
     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
 
     Austria        ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
@@ -968,14 +975,26 @@ You should try to choose one close to you:
     Denmark        ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
     Estonia        ftp://ftp.ut.ee/pub/languages/perl/CPAN/
     Finland        ftp://ftp.funet.fi/pub/languages/perl/CPAN/
-    France         ftp://ftp.lip6.fr/pub/perl/CPAN/
+    France         ftp://ftp.grolier.fr/pub/perl/CPAN/
+                   ftp://ftp.lip6.fr/pub/perl/CPAN/
                    ftp://ftp.oleane.net/pub/mirrors/CPAN/
                    ftp://ftp.pasteur.fr/pub/computing/CPAN/
                    ftp://ftp.uvsq.fr/pub/perl/CPAN/
+    German         ftp://ftp.gigabell.net/pub/CPAN/
     Germany        ftp://ftp.archive.de.uu.net/pub/CPAN/
+                   ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/
                    ftp://ftp.gmd.de/packages/CPAN/
                    ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
-                   ftp://ftp.leo.org/pub/comp/programming/languages/script/perl/CPAN/
+                   ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
+                   ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
+                   ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
+                   ftp://ftp.uni-erlangen.de/pub/source/CPAN/
+                   ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
+    Germany        ftp://ftp.archive.de.uu.net/pub/CPAN/
+                   ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/
+                   ftp://ftp.gmd.de/packages/CPAN/
+                   ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
+                   ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
                    ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
                    ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
                    ftp://ftp.uni-erlangen.de/pub/source/CPAN/
@@ -990,19 +1009,16 @@ You should try to choose one close to you:
                    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/
-    Poland         ftp://ftp.man.szczecin.pl/pub/perl/CPAN/
-                   ftp://ftp.man.torun.pl/pub/doc/CPAN/
+    Poland         ftp://ftp.man.torun.pl/pub/CPAN/
                    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/
+    Romania        ftp://ftp.dnttm.ro/pub/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/
@@ -1018,19 +1034,17 @@ You should try to choose one close to you:
                    ftp://ftp.plig.org/pub/CPAN/
                    ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
 
+
 =item North America
 
     Alberta        ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
     California     ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
                    ftp://cpan.valueclick.com/CPAN/
                    ftp://ftp.cdrom.com/pub/perl/CPAN/
-                   ftp://ftp.digital.com/pub/plan/perl/CPAN/
-    California     ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
-                   ftp://cpan.valueclick.com/CPAN/
-                   ftp://ftp.cdrom.com/pub/perl/CPAN/
-                   ftp://ftp.digital.com/pub/plan/perl/CPAN/
+                   http://download.sourceforge.net/mirrors/CPAN/
     Colorado       ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
     Florida        ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
+    Georgia        ftp://ftp.twoguys.org/CPAN/
     Illinois       ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/
     Indiana        ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/
                    ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
@@ -1039,34 +1053,35 @@ You should try to choose one close to you:
     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         ftp://ftp.msg.com.mx/pub/CPAN/
-    Minnesota      ftp://ftp.midearthbbs.com/CPAN/
     New York       ftp://ftp.deao.net/pub/CPAN/
                    ftp://ftp.rge.com/pub/languages/perl/
-                   ftp://ftp.tpj.com/pub/CPAN/
-    Nova Scotia    ftp://cpan.chebucto.ns.ca/pub/CPAN/
     North Carolina ftp://ftp.duke.edu/pub/perl/
+    Nova Scotia    ftp://cpan.chebucto.ns.ca/pub/CPAN/
     Oklahoma       ftp://ftp.ou.edu/mirrors/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/
     Tennessee      ftp://ftp.sunsite.utk.edu/pub/CPAN/
     Texas          ftp://ftp.sedl.org/pub/mirrors/CPAN/
+                   ftp://jhcloos.com/pub/mirror/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-mirror.internap.com/pub/CPAN/
+                   ftp://ftp.llarian.net/pub/CPAN/
                    ftp://ftp.spu.edu/pub/CPAN/
 
+
 =item South America
 
     Brazil         ftp://cpan.if.usp.br/pub/mirror/CPAN/
                    ftp://ftp.matrix.com.br/pub/perl/
-    Chile          ftp://sunsite.dcc.uchile.cl/pub/Lang/perl/CPAN/
+    Chile          ftp://sunsite.dcc.uchile.cl/pub/Lang/PERL/
 
 =back
 
 For an up-to-date listing of CPAN sites,
-see http://www.perl.com/perl/CPAN or ftp://www.perl.com/perl/ .
+see http://www.perl.com/perl/CPAN/SITES or ftp://www.perl.com/CPAN/SITES .
 
 =head1 Modules: Creation, Use, and Abuse
 
@@ -1110,7 +1125,9 @@ scheme as the original author.
 
 =item Try to design the new module to be easy to extend and reuse.
 
-Always use B<-w>.  
+Try to C<use warnings;> (or C<use warnings qw(...);>).
+Remember that you can add C<no warnings qw(...);> to individual blocks
+of code that need less warnings.  
 
 Use blessed references.  Use the two argument form of bless to bless
 into the class name given as the first parameter of the constructor,
@@ -1140,8 +1157,8 @@ 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.
 
-Avoid C<$r-E<gt>Class::func()> where using C<@ISA=qw(... Class ...)> and
-C<$r-E<gt>func()> would work (see L<perlbot> for more details).
+Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
+C<< $r->func() >> would work (see L<perlbot> for more details).
 
 Use autosplit so little used or newly added functions won't be a
 burden to programs that don't use them. Add test functions to
@@ -1198,7 +1215,7 @@ or nature of a variable. For example:
  $no_caps_here    function scope my() or local() variables
 
 Function and method names seem to work best as all lowercase.
-e.g., C<$obj-E<gt>as_string()>.
+e.g., C<< $obj->as_string() >>.
 
 You can use a leading underscore to indicate that a variable or
 function should not be used outside the package that defined it.
@@ -1214,7 +1231,7 @@ export try to use @EXPORT_OK in preference to @EXPORT and avoid
 short or common names to reduce the risk of name clashes.
 
 Generally anything not exported is still accessible from outside the
-module using the ModuleName::item_name (or C<$blessed_ref-E<gt>method>)
+module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
 syntax.  By convention you can use a leading underscore on names to
 indicate informally that they are 'internal' and not for public use.
 
@@ -1368,16 +1385,17 @@ location.
 
 FTP Archives for Perl Modules:
 
-Follow the instructions and links on
+Follow the instructions and links on:
 
-   http://franz.ww.tu-berlin.de/modulelist
+   http://www.perl.com/CPAN/modules/00modlist.long.html
+   http://www.perl.com/CPAN/modules/04pause.html
 
 or upload to one of these sites:
 
-   ftp://franz.ww.tu-berlin.de/incoming
-   ftp://ftp.cis.ufl.edu/incoming
+   https://pause.kbx.de/pause/
+   http://pause.perl.org/pause/
 
-and notify <F<upload@franz.ww.tu-berlin.de>>.
+and notify <modules@perl.org>.
 
 By using the WWW interface you can ask the Upload Server to mirror
 your modules from your ftp or WWW site into your own directory on