pod/perlmodlib.PL

   1 #!../miniperl
   2
   3 use strict;
   4 use warnings;
   5
   6 $ENV{LC_ALL} = 'C';
   7
   8 my $Quiet;
   9 @ARGV = grep { not($_ eq '-q' and $Quiet = 1) } @ARGV;
  10
  11 if (@ARGV) {
  12     my $workdir = shift;
  13     chdir $workdir
  14         or die "Couldn't chdir to '$workdir': $!";
  15 }
  16 require 'regen/regen_lib.pl';
  17
  18 # MANIFEST itself is Unix style filenames, so we have to assume that Unix style
  19 # filenames will work.
  20
  21 open MANIFEST, '<', 'MANIFEST'
  22     or die "Can't open MANIFEST: $!";
  23 my @files = grep m#(?:\.pm|\.pod|_pm\.PL)#, map {s/\s.*//s; $_}
  24     grep { m#^(lib|ext|dist|cpan)/# && !m#/(?:t|demo)/# } <MANIFEST>;
  25 close MANIFEST
  26     or die "$0: failed to close MANIFEST: $!";
  27
  28 my $out = open_new('pod/perlmodlib.pod', undef,
  29                    {by => "$0 extracting documentation",
  30                     from => 'the Perl source files'}, 1);
  31
  32 my %exceptions = (
  33     'abbrev' => 'Text::Abbrev',
  34     'carp' => 'Carp',
  35     'getopt' => 'Getopt::Std',
  36     'B<CGI::Carp>' => 'CGI::Carp',
  37     'ModuleInfo' => 'Module::Build::ModuleInfo',
  38     '$notes_name' => 'Module::Build::Notes',
  39     'Encode::MIME::NAME' => 'Encode::MIME::Name',
  40     'libnetFAQ' => 'Net::libnetFAQ',
  41 );
  42
  43 my (@pragma, @mod);
  44
  45 for my $filename (@files) {
  46     unless (open MOD, '<', $filename) {
  47         warn "Couldn't open $filename: $!";
  48         next;
  49     }
  50
  51     my ($name, $thing);
  52     my $foundit = 0;
  53     {
  54         local $/ = "";
  55         while (<MOD>) {
  56             next unless /^=head1 NAME/;
  57             $foundit++;
  58             last;
  59         }
  60     }
  61     unless ($foundit) {
  62         warn "$filename missing =head1 NAME (OK if respective .pod exists)\n"
  63             unless $Quiet;
  64         next;
  65     }
  66     my $title = <MOD>;
  67     chomp $title;
  68     close MOD
  69         or die "Error closing $filename: $!";
  70
  71     ($name, $thing) = split / --? /, $title, 2;
  72
  73     unless ($name and $thing) {
  74         warn "$filename missing name\n"  unless $name;
  75         warn "$filename missing thing\n" unless $thing or $Quiet;
  76         next;
  77     }
  78
  79     $name =~ s/[^A-Za-z0-9_:\$<>].*//;
  80     $name = $exceptions{$name} || $name;
  81     $thing =~ s/^perl pragma to //i;
  82     $thing = ucfirst $thing;
  83     $title = "=item $name\n\n$thing\n\n";
  84
  85     if ($name =~ /[A-Z]/) {
  86         push @mod, $title;
  87     } else {
  88         push @pragma, $title;
  89     }
  90 }
  91
  92 # Much easier to special case it like this than special case the depending on
  93 # and parsing lib/Config.pod, or special case opening configpm and finding its
  94 # =head1 (which is not found with the $/="" above)
  95 push @mod, "=item Config\n\nAccess Perl configuration information\n\n";
  96
  97
  98 # The intent of using =cut as the heredoc terminator is to make the whole file
  99 # parse as (reasonably) sane Pod as-is to anything that attempts to
 100 # brute-force treat it as such. The content is already useful - this just
 101 # makes it tidier, by stopping anything doing this mistaking the rest of the
 102 # Perl code for Pod. eg http://search.cpan.org/dist/perl/pod/perlmodlib.PL
 103
 104 print $out <<'=cut';
 105 =head1 NAME
 106
 107 perlmodlib - constructing new Perl modules and finding existing ones
 108
 109 =head1 THE PERL MODULE LIBRARY
 110
 111 Many modules are included in the Perl distribution.  These are described
 112 below, and all end in F<.pm>.  You may discover compiled library
 113 files (usually ending in F<.so>) or small pieces of modules to be
 114 autoloaded (ending in F<.al>); these were automatically generated
 115 by the installation process.  You may also discover files in the
 116 library directory that end in either F<.pl> or F<.ph>.  These are
 117 old libraries supplied so that old programs that use them still
 118 run.  The F<.pl> files will all eventually be converted into standard
 119 modules, and the F<.ph> files made by B<h2ph> will probably end up
 120 as extension modules made by B<h2xs>.  (Some F<.ph> values may
 121 already be available through the POSIX, Errno, or Fcntl modules.)
 122 The B<pl2pm> file in the distribution may help in your conversion,
 123 but it's just a mechanical process and therefore far from bulletproof.
 124
 125 =head2 Pragmatic Modules
 126
 127 They work somewhat like compiler directives (pragmata) in that they
 128 tend to affect the compilation of your program, and thus will usually
 129 work well only when used within a C<use>, or C<no>.  Most of these
 130 are lexically scoped, so an inner BLOCK may countermand them
 131 by saying:
 132
 133     no integer;
 134     no strict 'refs';
 135     no warnings;
 136
 137 which lasts until the end of that BLOCK.
 138
 139 Some pragmas are lexically scoped--typically those that affect the
 140 C<$^H> hints variable.  Others affect the current package instead,
 141 like C<use vars> and C<use subs>, which allow you to predeclare a
 142 variables or subroutines within a particular I<file> rather than
 143 just a block.  Such declarations are effective for the entire file
 144 for which they were declared.  You cannot rescind them with C<no
 145 vars> or C<no subs>.
 146
 147 The following pragmas are defined (and have their own documentation).
 148
 149 =over 12
 150
 151 =cut
 152
 153 print $out $_ for sort @pragma;
 154
 155 print $out <<'=cut';
 156
 157 =back
 158
 159 =head2 Standard Modules
 160
 161 Standard, bundled modules are all expected to behave in a well-defined
 162 manner with respect to namespace pollution because they use the
 163 Exporter module.  See their own documentation for details.
 164
 165 It's possible that not all modules listed below are installed on your
 166 system. For example, the GDBM_File module will not be installed if you
 167 don't have the gdbm library.
 168
 169 =over 12
 170
 171 =cut
 172
 173 print $out $_ for sort @mod;
 174
 175 print $out <<'=cut', "=cut\n";
 176
 177 =back
 178
 179 To find out I<all> modules installed on your system, including
 180 those without documentation or outside the standard release,
 181 just use the following command (under the default win32 shell,
 182 double quotes should be used instead of single quotes).
 183
 184     % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \
 185       'find { wanted => sub { print canonpath $_ if /\.pm\z/ },
 186       no_chdir => 1 }, @INC'
 187
 188 (The -T is here to prevent '.' from being listed in @INC.)
 189 They should all have their own documentation installed and accessible
 190 via your system man(1) command.  If you do not have a B<find>
 191 program, you can use the Perl B<find2perl> program instead, which
 192 generates Perl code as output you can run through perl.  If you
 193 have a B<man> program but it doesn't find your modules, you'll have
 194 to fix your manpath.  See L<perl> for details.  If you have no
 195 system B<man> command, you might try the B<perldoc> program.
 196
 197 Note also that the command C<perldoc perllocal> gives you a (possibly
 198 incomplete) list of the modules that have been further installed on
 199 your system. (The perllocal.pod file is updated by the standard MakeMaker
 200 install process.)
 201
 202 =head2 Extension Modules
 203
 204 Extension modules are written in C (or a mix of Perl and C).  They
 205 are usually dynamically loaded into Perl if and when you need them,
 206 but may also be linked in statically.  Supported extension modules
 207 include Socket, Fcntl, and POSIX.
 208
 209 Many popular C extension modules do not come bundled (at least, not
 210 completely) due to their sizes, volatility, or simply lack of time
 211 for adequate testing and configuration across the multitude of
 212 platforms on which Perl was beta-tested.  You are encouraged to
 213 look for them on CPAN (described below), or using web search engines
 214 like Alta Vista or Google.
 215
 216 =head1 CPAN
 217
 218 CPAN stands for Comprehensive Perl Archive Network; it's a globally
 219 replicated trove of Perl materials, including documentation, style
 220 guides, tricks and traps, alternate ports to non-Unix systems and
 221 occasional binary distributions for these.   Search engines for
 222 CPAN can be found at http://www.cpan.org/
 223
 224 Most importantly, CPAN includes around a thousand unbundled modules,
 225 some of which require a C compiler to build.  Major categories of
 226 modules are:
 227
 228 =over
 229
 230 =item *
 231
 232 Language Extensions and Documentation Tools
 233
 234 =item *
 235
 236 Development Support
 237
 238 =item *
 239
 240 Operating System Interfaces
 241
 242 =item *
 243
 244 Networking, Device Control (modems) and InterProcess Communication
 245
 246 =item *
 247
 248 Data Types and Data Type Utilities
 249
 250 =item *
 251
 252 Database Interfaces
 253
 254 =item *
 255
 256 User Interfaces
 257
 258 =item *
 259
 260 Interfaces to / Emulations of Other Programming Languages
 261
 262 =item *
 263
 264 File Names, File Systems and File Locking (see also File Handles)
 265
 266 =item *
 267
 268 String Processing, Language Text Processing, Parsing, and Searching
 269
 270 =item *
 271
 272 Option, Argument, Parameter, and Configuration File Processing
 273
 274 =item *
 275
 276 Internationalization and Locale
 277
 278 =item *
 279
 280 Authentication, Security, and Encryption
 281
 282 =item *
 283
 284 World Wide Web, HTML, HTTP, CGI, MIME
 285
 286 =item *
 287
 288 Server and Daemon Utilities
 289
 290 =item *
 291
 292 Archiving and Compression
 293
 294 =item *
 295
 296 Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
 297
 298 =item *
 299
 300 Mail and Usenet News
 301
 302 =item *
 303
 304 Control Flow Utilities (callbacks and exceptions etc)
 305
 306 =item *
 307
 308 File Handle and Input/Output Stream Utilities
 309
 310 =item *
 311
 312 Miscellaneous Modules
 313
 314 =back
 315
 316 The list of the registered CPAN sites follows.
 317 Please note that the sorting order is alphabetical on fields:
 318
 319 Continent
 320    |
 321    |-->Country
 322          |
 323          |-->[state/province]
 324                    |
 325                    |-->ftp
 326                    |
 327                    |-->[http]
 328
 329 and thus the North American servers happen to be listed between the
 330 European and the South American sites.
 331
 332 Registered CPAN sites
 333
 334 =for maintainers
 335 Generated by Porting/make_modlib_cpan.pl
 336
 337 =head2 Africa
 338
 339 =over 4
 340
 341 =item South Africa
 342
 343   http://cpan.mirror.ac.za/
 344   ftp://cpan.mirror.ac.za/
 345   http://mirror.is.co.za/pub/cpan/
 346   ftp://ftp.is.co.za/pub/cpan/
 347   ftp://ftp.saix.net/pub/CPAN/
 348
 349 =back
 350
 351 =head2 Asia
 352
 353 =over 4
 354
 355 =item China
 356
 357   http://cpan.wenzk.com/
 358
 359 =item Hong Kong
 360
 361   http://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
 362   ftp://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
 363   http://mirrors.geoexpat.com/cpan/
 364
 365 =item India
 366
 367   http://perlmirror.indialinks.com/
 368
 369 =item Indonesia
 370
 371   http://cpan.biz.net.id/
 372   http://komo.vlsm.org/CPAN/
 373   ftp://komo.vlsm.org/CPAN/
 374   http://cpan.cermin.lipi.go.id/
 375   ftp://cermin.lipi.go.id/pub/CPAN/
 376   http://cpan.pesat.net.id/
 377
 378 =item Japan
 379
 380   ftp://ftp.u-aizu.ac.jp/pub/CPAN
 381   ftp://ftp.kddilabs.jp/CPAN/
 382   http://ftp.nara.wide.ad.jp/pub/CPAN/
 383   ftp://ftp.nara.wide.ad.jp/pub/CPAN/
 384   http://ftp.jaist.ac.jp/pub/CPAN/
 385   ftp://ftp.jaist.ac.jp/pub/CPAN/
 386   ftp://ftp.dti.ad.jp/pub/lang/CPAN/
 387   ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
 388   http://ftp.riken.jp/lang/CPAN/
 389   ftp://ftp.riken.jp/lang/CPAN/
 390   http://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
 391   ftp://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
 392
 393 =item Republic of Korea
 394
 395   http://ftp.kaist.ac.kr/pub/CPAN
 396   ftp://ftp.kaist.ac.kr/pub/CPAN
 397   http://cpan.mirror.cdnetworks.com/
 398   ftp://cpan.mirror.cdnetworks.com/CPAN/
 399   http://cpan.sarang.net/
 400   ftp://cpan.sarang.net/CPAN/
 401
 402 =item Russia
 403
 404   http://cpan.tomsk.ru/
 405   ftp://cpan.tomsk.ru/
 406
 407 =item Singapore
 408
 409   http://mirror.averse.net/pub/CPAN
 410   ftp://mirror.averse.net/pub/CPAN
 411   http://cpan.mirror.choon.net/
 412   http://cpan.oss.eznetsols.org
 413   ftp://ftp.oss.eznetsols.org/cpan
 414
 415 =item Taiwan
 416
 417   http://ftp.cse.yzu.edu.tw/pub/CPAN/
 418   ftp://ftp.cse.yzu.edu.tw/pub/CPAN/
 419   http://cpan.nctu.edu.tw/
 420   ftp://cpan.nctu.edu.tw/
 421   ftp://ftp.ncu.edu.tw/CPAN/
 422   http://cpan.cdpa.nsysu.edu.tw/
 423   ftp://cpan.cdpa.nsysu.edu.tw/Unix/Lang/CPAN/
 424   http://cpan.stu.edu.tw
 425   ftp://ftp.stu.edu.tw/CPAN
 426   http://ftp.stu.edu.tw/CPAN
 427   ftp://ftp.stu.edu.tw/pub/CPAN
 428   http://cpan.cs.pu.edu.tw/
 429   ftp://cpan.cs.pu.edu.tw/pub/CPAN
 430
 431 =item Thailand
 432
 433   http://mirrors.issp.co.th/cpan/
 434   ftp://mirrors.issp.co.th/cpan/
 435   http://mirror.yourconnect.com/CPAN/
 436   ftp://mirror.yourconnect.com/CPAN/
 437
 438 =item Turkey
 439
 440   http://cpan.gazi.edu.tr/
 441
 442 =back
 443
 444 =head2 Central America
 445
 446 =over 4
 447
 448 =item Costa Rica
 449
 450   http://mirrors.ucr.ac.cr/CPAN/
 451   ftp://mirrors.ucr.ac.cr/CPAN/
 452
 453 =back
 454
 455 =head2 Europe
 456
 457 =over 4
 458
 459 =item Austria
 460
 461   http://cpan.inode.at/
 462   ftp://cpan.inode.at
 463   http://gd.tuwien.ac.at/languages/perl/CPAN/
 464   ftp://gd.tuwien.ac.at/pub/CPAN/
 465
 466 =item Belgium
 467
 468   http://ftp.belnet.be/mirror/ftp.cpan.org/
 469   ftp://ftp.belnet.be/mirror/ftp.cpan.org/
 470   http://ftp.easynet.be/pub/CPAN/
 471   http://cpan.weepee.org/
 472
 473 =item Bosnia and Herzegovina
 474
 475   http://cpan.blic.net/
 476
 477 =item Bulgaria
 478
 479   http://cpan.cbox.biz/
 480   ftp://cpan.cbox.biz/cpan/
 481   http://cpan.digsys.bg/
 482   ftp://ftp.digsys.bg/pub/CPAN
 483
 484 =item Croatia
 485
 486   http://ftp.carnet.hr/pub/CPAN/
 487   ftp://ftp.carnet.hr/pub/CPAN/
 488
 489 =item Czech Republic
 490
 491   ftp://ftp.fi.muni.cz/pub/CPAN/
 492   http://archive.cpan.cz/
 493
 494 =item Denmark
 495
 496   http://mirrors.dotsrc.org/cpan
 497   ftp://mirrors.dotsrc.org/cpan/
 498   http://www.cpan.dk/
 499   http://mirror.uni-c.dk/pub/CPAN/
 500
 501 =item Finland
 502
 503   ftp://ftp.funet.fi/pub/languages/perl/CPAN/
 504   http://mirror.eunet.fi/CPAN
 505
 506 =item France
 507
 508   http://cpan.enstimac.fr/
 509   ftp://ftp.inria.fr/pub/CPAN/
 510   http://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
 511   ftp://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
 512   ftp://ftp.lip6.fr/pub/perl/CPAN/
 513   http://mir2.ovh.net/ftp.cpan.org
 514   ftp://mir1.ovh.net/ftp.cpan.org
 515   ftp://ftp.oleane.net/pub/CPAN/
 516   http://ftp.crihan.fr/mirrors/ftp.cpan.org/
 517   ftp://ftp.crihan.fr/mirrors/ftp.cpan.org/
 518   http://ftp.u-strasbg.fr/CPAN
 519   ftp://ftp.u-strasbg.fr/CPAN
 520   http://cpan.cict.fr/
 521   ftp://cpan.cict.fr/pub/CPAN/
 522
 523 =item Germany
 524
 525   ftp://ftp.fu-berlin.de/unix/languages/perl/
 526   http://mirrors.softliste.de/cpan/
 527   ftp://ftp.rub.de/pub/CPAN/
 528   http://www.planet-elektronik.de/CPAN/
 529   http://ftp.hosteurope.de/pub/CPAN/
 530   ftp://ftp.hosteurope.de/pub/CPAN/
 531   http://www.mirrorspace.org/cpan/
 532   http://mirror.netcologne.de/cpan/
 533   ftp://mirror.netcologne.de/cpan/
 534   ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
 535   http://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/
 536   ftp://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/
 537   http://mirrors.zerg.biz/cpan/
 538   http://ftp.gwdg.de/pub/languages/perl/CPAN/
 539   ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
 540   http://dl.ambiweb.de/mirrors/ftp.cpan.org/
 541   http://cpan.mirror.clusters.kg/
 542   http://cpan.mirror.iphh.net/
 543   ftp://cpan.mirror.iphh.net/pub/CPAN/
 544   http://cpan.mirroring.de/
 545   http://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/
 546   ftp://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/
 547   http://www.chemmedia.de/mirrors/CPAN/
 548   http://ftp.cw.net/pub/CPAN/
 549   ftp://ftp.cw.net/pub/CPAN/
 550   http://cpan.cpantesters.org/
 551   ftp://cpan.cpantesters.org/CPAN/
 552   http://cpan.mirrored.de/
 553   ftp://mirror.petamem.com/CPAN/
 554   http://cpan.noris.de/
 555   ftp://cpan.noris.de/pub/CPAN/
 556   ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
 557   ftp://ftp.gmd.de/mirrors/CPAN/
 558
 559 =item Greece
 560
 561   ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
 562   ftp://ftp.ntua.gr/pub/lang/perl/
 563   http://cpan.cc.uoc.gr/
 564   ftp://ftp.cc.uoc.gr/mirrors/CPAN/
 565
 566 =item Hungary
 567
 568   http://cpan.mirrors.enexis.hu/
 569   ftp://cpan.mirrors.enexis.hu/mirrors/cpan/
 570   http://cpan.hu/
 571
 572 =item Iceland
 573
 574   http://ftp.rhnet.is/pub/CPAN/
 575   ftp://ftp.rhnet.is/pub/CPAN/
 576
 577 =item Ireland
 578
 579   http://ftp.esat.net/pub/languages/perl/CPAN/
 580   ftp://ftp.esat.net/pub/languages/perl/CPAN/
 581   http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
 582   ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
 583
 584 =item Italy
 585
 586   http://bo.mirror.garr.it/mirrors/CPAN/
 587   http://cpan.panu.it/
 588   ftp://ftp.panu.it/pub/mirrors/perl/CPAN/
 589
 590 =item Latvia
 591
 592   http://kvin.lv/pub/CPAN/
 593
 594 =item Lithuania
 595
 596   http://ftp.litnet.lt/pub/CPAN/
 597   ftp://ftp.litnet.lt/pub/CPAN/
 598
 599 =item Malta
 600
 601   http://cpan.waldonet.net.mt/
 602
 603 =item Netherlands
 604
 605   ftp://ftp.quicknet.nl/pub/CPAN/
 606   http://mirror.hostfuss.com/CPAN/
 607   ftp://mirror.hostfuss.com/CPAN/
 608   http://mirrors3.kernel.org/cpan/
 609   ftp://mirrors3.kernel.org/pub/CPAN/
 610   http://cpan.mirror.versatel.nl/
 611   ftp://ftp.mirror.versatel.nl/cpan/
 612   ftp://download.xs4all.nl/pub/mirror/CPAN/
 613   http://mirror.leaseweb.com/CPAN/
 614   ftp://mirror.leaseweb.com/CPAN/
 615   ftp://ftp.cpan.nl/pub/CPAN/
 616   http://archive.cs.uu.nl/mirror/CPAN/
 617   ftp://ftp.cs.uu.nl/mirror/CPAN/
 618   http://luxitude.net/cpan/
 619
 620 =item Norway
 621
 622   ftp://ftp.uninett.no/pub/languages/perl/CPAN
 623   ftp://ftp.uit.no/pub/languages/perl/cpan/
 624
 625 =item Poland
 626
 627   http://piotrkosoft.net/pub/mirrors/CPAN/
 628   ftp://ftp.piotrkosoft.net/pub/mirrors/CPAN/
 629   http://ftp.man.poznan.pl/pub/CPAN
 630   ftp://ftp.man.poznan.pl/pub/CPAN
 631   ftp://ftp.ps.pl/pub/CPAN/
 632   ftp://sunsite.icm.edu.pl/pub/CPAN/
 633   ftp://ftp.tpnet.pl/d4/CPAN/
 634
 635 =item Portugal
 636
 637   http://cpan.dei.uc.pt/
 638   ftp://ftp.dei.uc.pt/pub/CPAN
 639   ftp://ftp.ist.utl.pt/pub/CPAN/
 640   http://cpan.perl.pt/
 641   http://cpan.ip.pt/
 642   ftp://cpan.ip.pt/pub/cpan/
 643   http://mirrors.nfsi.pt/CPAN/
 644   ftp://mirrors.nfsi.pt/pub/CPAN/
 645   http://cpan.dcc.fc.up.pt/
 646
 647 =item Romania
 648
 649   http://ftp.astral.ro/pub/CPAN/
 650   ftp://ftp.astral.ro/pub/CPAN/
 651   ftp://ftp.lug.ro/CPAN
 652   http://mirrors.xservers.ro/CPAN/
 653   http://mirrors.hostingromania.ro/ftp.cpan.org/
 654   ftp://ftp.hostingromania.ro/mirrors/ftp.cpan.org/
 655   ftp://ftp.iasi.roedu.net/pub/mirrors/ftp.cpan.org/
 656
 657 =item Russia
 658
 659   ftp://ftp.aha.ru/CPAN/
 660   http://cpan.rinet.ru/
 661   ftp://cpan.rinet.ru/pub/mirror/CPAN/
 662   ftp://ftp.SpringDaemons.com/pub/CPAN/
 663   http://mirror.rol.ru/CPAN/
 664   http://ftp.silvernet.ru/CPAN/
 665   http://ftp.spbu.ru/CPAN/
 666   ftp://ftp.spbu.ru/CPAN/
 667
 668 =item Slovakia
 669
 670   http://cpan.fyxm.net/
 671
 672 =item Slovenia
 673
 674   http://www.klevze.si/cpan
 675
 676 =item Spain
 677
 678   http://osl.ugr.es/CPAN/
 679   ftp://ftp.rediris.es/mirror/CPAN/
 680   http://ftp.gui.uva.es/sites/cpan.org/
 681   ftp://ftp.gui.uva.es/sites/cpan.org/
 682
 683 =item Sweden
 684
 685   http://mirrors4.kernel.org/cpan/
 686   ftp://mirrors4.kernel.org/pub/CPAN/
 687
 688 =item Switzerland
 689
 690   http://cpan.mirror.solnet.ch/
 691   ftp://ftp.solnet.ch/mirror/CPAN/
 692   ftp://ftp.adwired.ch/CPAN/
 693   http://mirror.switch.ch/ftp/mirror/CPAN/
 694   ftp://mirror.switch.ch/mirror/CPAN/
 695
 696 =item Ukraine
 697
 698   http://cpan.makeperl.org/
 699   ftp://cpan.makeperl.org/pub/CPAN
 700   http://cpan.org.ua/
 701   http://cpan.gafol.net/
 702   ftp://ftp.gafol.net/pub/cpan/
 703
 704 =item United Kingdom
 705
 706   http://www.mirrorservice.org/sites/ftp.funet.fi/pub/languages/perl/CPAN/
 707   ftp://ftp.mirrorservice.org/sites/ftp.funet.fi/pub/languages/perl/CPAN/
 708   http://mirror.tje.me.uk/pub/mirrors/ftp.cpan.org/
 709   ftp://mirror.tje.me.uk/pub/mirrors/ftp.cpan.org/
 710   http://www.mirror.8086.net/sites/CPAN/
 711   ftp://ftp.mirror.8086.net/sites/CPAN/
 712   http://cpan.mirror.anlx.net/
 713   ftp://ftp.mirror.anlx.net/CPAN/
 714   http://mirror.bytemark.co.uk/CPAN/
 715   ftp://mirror.bytemark.co.uk/CPAN/
 716   http://cpan.etla.org/
 717   ftp://cpan.etla.org/pub/CPAN
 718   ftp://ftp.demon.co.uk/pub/CPAN/
 719   http://mirror.sov.uk.goscomb.net/CPAN/
 720   ftp://mirror.sov.uk.goscomb.net/pub/CPAN/
 721   http://ftp.plig.net/pub/CPAN/
 722   ftp://ftp.plig.net/pub/CPAN/
 723   http://ftp.ticklers.org/pub/CPAN/
 724   ftp://ftp.ticklers.org/pub/CPAN/
 725   http://cpan.mirrors.uk2.net/
 726   ftp://mirrors.uk2.net/pub/CPAN/
 727   http://mirror.ox.ac.uk/sites/www.cpan.org/
 728   ftp://mirror.ox.ac.uk/sites/www.cpan.org/
 729
 730 =back
 731
 732 =head2 North America
 733
 734 =over 4
 735
 736 =item Bahamas
 737
 738   http://www.securehost.com/mirror/CPAN/
 739
 740 =item Canada
 741
 742   http://cpan.arcticnetwork.ca
 743   ftp://mirror.arcticnetwork.ca/pub/CPAN
 744   http://cpan.sunsite.ualberta.ca/
 745   ftp://cpan.sunsite.ualberta.ca/pub/CPAN/
 746   http://theoryx5.uwinnipeg.ca/pub/CPAN/
 747   ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
 748   http://arwen.cs.dal.ca/mirror/CPAN/
 749   ftp://arwen.cs.dal.ca/pub/mirror/CPAN/
 750   http://CPAN.mirror.rafal.ca/
 751   ftp://CPAN.mirror.rafal.ca/pub/CPAN/
 752   ftp://ftp.nrc.ca/pub/CPAN/
 753   http://mirror.csclub.uwaterloo.ca/pub/CPAN/
 754   ftp://mirror.csclub.uwaterloo.ca/pub/CPAN/
 755
 756 =item Mexico
 757
 758   http://www.msg.com.mx/CPAN/
 759   ftp://ftp.msg.com.mx/pub/CPAN/
 760
 761 =item United States
 762
 763 =over 8
 764
 765 =item Alabama
 766
 767   http://mirror.hiwaay.net/CPAN/
 768   ftp://mirror.hiwaay.net/CPAN/
 769
 770 =item Arizona
 771
 772   http://cpan.ezarticleinformation.com/
 773
 774 =item California
 775
 776   http://cpan.knowledgematters.net/
 777   http://cpan.binkerton.com/
 778   http://cpan.develooper.com/
 779   http://mirrors.gossamer-threads.com/CPAN
 780   http://cpan.schatt.com/
 781   http://mirrors.kernel.org/cpan/
 782   ftp://mirrors.kernel.org/pub/CPAN
 783   http://mirrors2.kernel.org/cpan/
 784   ftp://mirrors2.kernel.org/pub/CPAN/
 785   http://cpan.mirror.facebook.net/
 786   http://mirrors1.kernel.org/cpan/
 787   ftp://mirrors1.kernel.org/pub/CPAN/
 788   http://cpan-sj.viaverio.com/
 789   ftp://cpan-sj.viaverio.com/pub/CPAN/
 790   http://www.perl.com/CPAN/
 791
 792 =item Florida
 793
 794   ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/
 795   http://mirror.atlantic.net/pub/CPAN/
 796   ftp://mirror.atlantic.net/pub/CPAN/
 797
 798 =item Idaho
 799
 800   http://mirror.its.uidaho.edu/pub/cpan/
 801   ftp://mirror.its.uidaho.edu/cpan/
 802
 803 =item Illinois
 804
 805   http://cpan.mirrors.hoobly.com/
 806   http://cpan.uchicago.edu/pub/CPAN/
 807   ftp://cpan.uchicago.edu/pub/CPAN/
 808   http://mirrors.servercentral.net/CPAN/
 809   http://www.stathy.com/CPAN/
 810   ftp://www.stathy.com/CPAN/
 811
 812 =item Indiana
 813
 814   ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/
 815   http://cpan.netnitco.net/
 816   ftp://cpan.netnitco.net/pub/mirrors/CPAN/
 817   http://ftp.ndlug.nd.edu/pub/perl/
 818   ftp://ftp.ndlug.nd.edu/pub/perl/
 819
 820 =item Massachusetts
 821
 822   http://mirrors.ccs.neu.edu/CPAN/
 823
 824 =item Michigan
 825
 826   http://ftp.wayne.edu/cpan/
 827   ftp://ftp.wayne.edu/cpan/
 828
 829 =item Minnesota
 830
 831   http://cpan.msi.umn.edu/
 832
 833 =item New Jersey
 834
 835   http://mirror.datapipe.net/CPAN/
 836   ftp://mirror.datapipe.net/pub/CPAN/
 837
 838 =item New York
 839
 840   http://mirrors.24-7-solutions.net/pub/CPAN/
 841   ftp://mirrors.24-7-solutions.net/pub/CPAN/
 842   http://mirror.cc.columbia.edu/pub/software/cpan/
 843   ftp://mirror.cc.columbia.edu/pub/software/cpan/
 844   http://cpan.belfry.net/
 845   http://cpan.erlbaum.net/
 846   ftp://cpan.erlbaum.net/CPAN/
 847   http://cpan.hexten.net/
 848   ftp://cpan.hexten.net/
 849   ftp://mirror.nyi.net/CPAN/
 850   http://mirror.rit.edu/CPAN/
 851   ftp://mirror.rit.edu/CPAN/
 852
 853 =item North Carolina
 854
 855   http://www.ibiblio.org/pub/mirrors/CPAN
 856   ftp://ftp.ncsu.edu/pub/mirror/CPAN/
 857
 858 =item Oregon
 859
 860   http://ftp.osuosl.org/pub/CPAN/
 861   ftp://ftp.osuosl.org/pub/CPAN/
 862
 863 =item Pennsylvania
 864
 865   http://ftp.epix.net/CPAN/
 866   ftp://ftp.epix.net/pub/languages/perl/
 867   http://cpan.pair.com/
 868   ftp://cpan.pair.com/pub/CPAN/
 869
 870 =item South Carolina
 871
 872   http://cpan.mirror.clemson.edu/
 873
 874 =item Tennessee
 875
 876   http://mira.sunsite.utk.edu/CPAN/
 877
 878 =item Texas
 879
 880   http://mirror.uta.edu/CPAN
 881
 882 =item Utah
 883
 884   ftp://mirror.xmission.com/CPAN/
 885
 886 =item Virginia
 887
 888   http://cpan-du.viaverio.com/
 889   ftp://cpan-du.viaverio.com/pub/CPAN/
 890   http://perl.secsup.org/
 891   ftp://perl.secsup.org/pub/perl/
 892   ftp://mirror.cogentco.com/pub/CPAN/
 893
 894 =item Washington
 895
 896   http://cpan.llarian.net/
 897   ftp://cpan.llarian.net/pub/CPAN/
 898   ftp://ftp-mirror.internap.com/pub/CPAN/
 899
 900 =item Wisconsin
 901
 902   http://cpan.mirrors.tds.net
 903   ftp://cpan.mirrors.tds.net/pub/CPAN
 904   http://mirror.sit.wisc.edu/pub/CPAN/
 905   ftp://mirror.sit.wisc.edu/pub/CPAN/
 906
 907 =back
 908
 909 =back
 910
 911 =head2 Oceania
 912
 913 =over 4
 914
 915 =item Australia
 916
 917   http://mirror.internode.on.net/pub/cpan/
 918   ftp://mirror.internode.on.net/pub/cpan/
 919   http://cpan.mirror.aussiehq.net.au/
 920   http://mirror.as24220.net/cpan/
 921   ftp://mirror.as24220.net/cpan/
 922
 923 =item New Zealand
 924
 925   ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
 926   http://cpan.inspire.net.nz
 927   ftp://cpan.inspire.net.nz/cpan
 928   http://cpan.catalyst.net.nz/CPAN/
 929   ftp://cpan.catalyst.net.nz/pub/CPAN/
 930
 931 =back
 932
 933 =head2 South America
 934
 935 =over 4
 936
 937 =item Argentina
 938
 939   http://cpan.patan.com.ar/
 940   http://cpan.localhost.net.ar
 941   ftp://mirrors.localhost.net.ar/pub/mirrors/CPAN
 942
 943 =item Brazil
 944
 945   ftp://cpan.pop-mg.com.br/pub/CPAN/
 946   http://ftp.pucpr.br/CPAN
 947   ftp://ftp.pucpr.br/CPAN
 948   http://cpan.kinghost.net/
 949
 950 =item Chile
 951
 952   http://cpan.dcc.uchile.cl/
 953   ftp://cpan.dcc.uchile.cl/pub/lang/cpan/
 954
 955 =item Colombia
 956
 957   http://www.laqee.unal.edu.co/CPAN/
 958
 959 =back
 960
 961 =head2 RSYNC Mirrors
 962
 963                       mirror.as24220.net::cpan
 964                       cpan.inode.at::CPAN
 965                       gd.tuwien.ac.at::CPAN
 966                       ftp.belnet.be::packages/cpan
 967                       rsync.linorg.usp.br::CPAN
 968                       rsync.arcticnetwork.ca::CPAN
 969                       CPAN.mirror.rafal.ca::CPAN
 970                       mirror.csclub.uwaterloo.ca::CPAN
 971                       theoryx5.uwinnipeg.ca::CPAN
 972                       www.laqee.unal.edu.co::CPAN
 973                       mirror.uni-c.dk::CPAN
 974                       rsync.nic.funet.fi::CPAN
 975                       rsync://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
 976                       mir1.ovh.net::CPAN
 977                       miroir-francais.fr::cpan
 978                       ftp.crihan.fr::CPAN
 979                       rsync://mirror.cict.fr/cpan/
 980                       rsync://mirror.netcologne.de/cpan/
 981                       ftp-stud.hs-esslingen.de::CPAN/
 982                       ftp.gwdg.de::FTP/languages/perl/CPAN/
 983                       cpan.mirror.iphh.net::CPAN
 984                       cpan.cpantesters.org::cpan
 985                       cpan.hu::CPAN
 986                       komo.vlsm.org::CPAN
 987                       mirror.unej.ac.id::cpan
 988                       ftp.esat.net::/pub/languages/perl/CPAN
 989                       ftp.heanet.ie::mirrors/ftp.perl.org/pub/CPAN
 990                       rsync.panu.it::CPAN
 991                       cpan.fastbull.org::CPAN
 992                       ftp.kddilabs.jp::cpan
 993                       ftp.nara.wide.ad.jp::cpan/
 994                       rsync://ftp.jaist.ac.jp/pub/CPAN/
 995                       rsync://ftp.riken.jp/cpan/
 996                       mirror.linuxiso.kz::CPAN
 997                       rsync://mirrors3.kernel.org/mirrors/CPAN/
 998                       rsync://rsync.osmirror.nl/cpan/
 999                       mirror.leaseweb.com::CPAN
1000                       cpan.nautile.nc::CPAN
1001                       mirror.icis.pcz.pl::CPAN
1002                       piotrkosoft.net::mirrors/CPAN
1003                       rsync://cpan.perl.pt/
1004                       ftp.kaist.ac.kr::cpan
1005                       cpan.sarang.net::CPAN
1006                       mirror.averse.net::cpan
1007                       rsync.oss.eznetsols.org
1008                       mirror.ac.za::cpan
1009                       ftp.is.co.za::IS-Mirror/ftp.cpan.org/
1010                       rsync://ftp.gui.uva.es/cpan/
1011                       rsync://mirrors4.kernel.org/mirrors/CPAN/
1012                       ftp.solnet.ch::CPAN
1013                       ftp.ulak.net.tr::CPAN
1014                       gafol.net::cpan
1015                       rsync.mirrorservice.org::ftp.funet.fi/pub/
1016                       rsync://rsync.mirror.8086.net/CPAN/
1017                       rsync.mirror.anlx.net::CPAN
1018                       mirror.bytemark.co.uk::CPAN
1019                       ftp.plig.net::CPAN
1020                       rsync://ftp.ticklers.org:CPAN/
1021                       mirrors.ibiblio.org::CPAN
1022                       cpan-du.viaverio.com::CPAN
1023                       mirror.hiwaay.net::CPAN
1024                       rsync://mira.sunsite.utk.edu/CPAN/
1025                       cpan.mirrors.tds.net::CPAN
1026                       mirror.its.uidaho.edu::cpan
1027                       rsync://mirror.cc.columbia.edu::cpan/
1028                       ftp.fxcorporate.com::CPAN
1029                       rsync.atlantic.net::CPAN
1030                       mirrors.kernel.org::mirrors/CPAN
1031                       rsync://mirrors2.kernel.org/mirrors/CPAN/
1032                       cpan.pair.com::CPAN
1033                       rsync://mirror.rit.edu/CPAN/
1034                       rsync://mirror.facebook.net/cpan/
1035                       rsync://mirrors1.kernel.org/mirrors/CPAN/
1036                       cpan-sj.viaverio.com::CPAN
1037
1038 For an up-to-date listing of CPAN sites,
1039 see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES .
1040
1041 =head1 Modules: Creation, Use, and Abuse
1042
1043 (The following section is borrowed directly from Tim Bunce's modules
1044 file, available at your nearest CPAN site.)
1045
1046 Perl implements a class using a package, but the presence of a
1047 package doesn't imply the presence of a class.  A package is just a
1048 namespace.  A class is a package that provides subroutines that can be
1049 used as methods.  A method is just a subroutine that expects, as its
1050 first argument, either the name of a package (for "static" methods),
1051 or a reference to something (for "virtual" methods).
1052
1053 A module is a file that (by convention) provides a class of the same
1054 name (sans the .pm), plus an import method in that class that can be
1055 called to fetch exported symbols.  This module may implement some of
1056 its methods by loading dynamic C or C++ objects, but that should be
1057 totally transparent to the user of the module.  Likewise, the module
1058 might set up an AUTOLOAD function to slurp in subroutine definitions on
1059 demand, but this is also transparent.  Only the F<.pm> file is required to
1060 exist.  See L<perlsub>, L<perlobj>, and L<AutoLoader> for details about
1061 the AUTOLOAD mechanism.
1062
1063 =head2 Guidelines for Module Creation
1064
1065 =over 4
1066
1067 =item  *
1068
1069 Do similar modules already exist in some form?
1070
1071 If so, please try to reuse the existing modules either in whole or
1072 by inheriting useful features into a new class.  If this is not
1073 practical try to get together with the module authors to work on
1074 extending or enhancing the functionality of the existing modules.
1075 A perfect example is the plethora of packages in perl4 for dealing
1076 with command line options.
1077
1078 If you are writing a module to expand an already existing set of
1079 modules, please coordinate with the author of the package.  It
1080 helps if you follow the same naming scheme and module interaction
1081 scheme as the original author.
1082
1083 =item  *
1084
1085 Try to design the new module to be easy to extend and reuse.
1086
1087 Try to C<use warnings;> (or C<use warnings qw(...);>).
1088 Remember that you can add C<no warnings qw(...);> to individual blocks
1089 of code that need less warnings.
1090
1091 Use blessed references.  Use the two argument form of bless to bless
1092 into the class name given as the first parameter of the constructor,
1093 e.g.,:
1094
1095  sub new {
1096      my $class = shift;
1097      return bless {}, $class;
1098  }
1099
1100 or even this if you'd like it to be used as either a static
1101 or a virtual method.
1102
1103  sub new {
1104      my $self  = shift;
1105      my $class = ref($self) || $self;
1106      return bless {}, $class;
1107  }
1108
1109 Pass arrays as references so more parameters can be added later
1110 (it's also faster).  Convert functions into methods where
1111 appropriate.  Split large methods into smaller more flexible ones.
1112 Inherit methods from other modules if appropriate.
1113
1114 Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
1115 Generally you can delete the C<eq 'FOO'> part with no harm at all.
1116 Let the objects look after themselves! Generally, avoid hard-wired
1117 class names as far as possible.
1118
1119 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
1120 C<< $r->func() >> would work.
1121
1122 Use autosplit so little used or newly added functions won't be a
1123 burden to programs that don't use them. Add test functions to
1124 the module after __END__ either using AutoSplit or by saying:
1125
1126  eval join('',<main::DATA>) || die $@ unless caller();
1127
1128 Does your module pass the 'empty subclass' test? If you say
1129 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
1130 to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
1131 does your application still work if you change:  C<< $obj = YOURCLASS->new(); >>
1132 into: C<< $obj = SUBCLASS->new(); >> ?
1133
1134 Avoid keeping any state information in your packages. It makes it
1135 difficult for multiple other packages to use yours. Keep state
1136 information in objects.
1137
1138 Always use B<-w>.
1139
1140 Try to C<use strict;> (or C<use strict qw(...);>).
1141 Remember that you can add C<no strict qw(...);> to individual blocks
1142 of code that need less strictness.
1143
1144 Always use B<-w>.
1145
1146 Follow the guidelines in L<perlstyle>.
1147
1148 Always use B<-w>.
1149
1150 =item  *
1151
1152 Some simple style guidelines
1153
1154 The perlstyle manual supplied with Perl has many helpful points.
1155
1156 Coding style is a matter of personal taste. Many people evolve their
1157 style over several years as they learn what helps them write and
1158 maintain good code.  Here's one set of assorted suggestions that
1159 seem to be widely used by experienced developers:
1160
1161 Use underscores to separate words.  It is generally easier to read
1162 $var_names_like_this than $VarNamesLikeThis, especially for
1163 non-native speakers of English. It's also a simple rule that works
1164 consistently with VAR_NAMES_LIKE_THIS.
1165
1166 Package/Module names are an exception to this rule. Perl informally
1167 reserves lowercase module names for 'pragma' modules like integer
1168 and strict. Other modules normally begin with a capital letter and
1169 use mixed case with no underscores (need to be short and portable).
1170
1171 You may find it helpful to use letter case to indicate the scope
1172 or nature of a variable. For example:
1173
1174  $ALL_CAPS_HERE   constants only (beware clashes with Perl vars)
1175  $Some_Caps_Here  package-wide global/static
1176  $no_caps_here    function scope my() or local() variables
1177
1178 Function and method names seem to work best as all lowercase.
1179 e.g., C<< $obj->as_string() >>.
1180
1181 You can use a leading underscore to indicate that a variable or
1182 function should not be used outside the package that defined it.
1183
1184 =item  *
1185
1186 Select what to export.
1187
1188 Do NOT export method names!
1189
1190 Do NOT export anything else by default without a good reason!
1191
1192 Exports pollute the namespace of the module user.  If you must
1193 export try to use @EXPORT_OK in preference to @EXPORT and avoid
1194 short or common names to reduce the risk of name clashes.
1195
1196 Generally anything not exported is still accessible from outside the
1197 module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
1198 syntax.  By convention you can use a leading underscore on names to
1199 indicate informally that they are 'internal' and not for public use.
1200
1201 (It is actually possible to get private functions by saying:
1202 C<my $subref = sub { ... };  &$subref;>.  But there's no way to call that
1203 directly as a method, because a method must have a name in the symbol
1204 table.)
1205
1206 As a general rule, if the module is trying to be object oriented
1207 then export nothing. If it's just a collection of functions then
1208 @EXPORT_OK anything but use @EXPORT with caution.
1209
1210 =item  *
1211
1212 Select a name for the module.
1213
1214 This name should be as descriptive, accurate, and complete as
1215 possible.  Avoid any risk of ambiguity. Always try to use two or
1216 more whole words.  Generally the name should reflect what is special
1217 about what the module does rather than how it does it.  Please use
1218 nested module names to group informally or categorize a module.
1219 There should be a very good reason for a module not to have a nested name.
1220 Module names should begin with a capital letter.
1221
1222 Having 57 modules all called Sort will not make life easy for anyone
1223 (though having 23 called Sort::Quick is only marginally better :-).
1224 Imagine someone trying to install your module alongside many others.
1225 If in any doubt ask for suggestions in comp.lang.perl.misc.
1226
1227 If you are developing a suite of related modules/classes it's good
1228 practice to use nested classes with a common prefix as this will
1229 avoid namespace clashes. For example: Xyz::Control, Xyz::View,
1230 Xyz::Model etc. Use the modules in this list as a naming guide.
1231
1232 If adding a new module to a set, follow the original author's
1233 standards for naming modules and the interface to methods in
1234 those modules.
1235
1236 If developing modules for private internal or project specific use,
1237 that will never be released to the public, then you should ensure
1238 that their names will not clash with any future public module. You
1239 can do this either by using the reserved Local::* category or by
1240 using a category name that includes an underscore like Foo_Corp::*.
1241
1242 To be portable each component of a module name should be limited to
1243 11 characters. If it might be used on MS-DOS then try to ensure each is
1244 unique in the first 8 characters. Nested modules make this easier.
1245
1246 =item  *
1247
1248 Have you got it right?
1249
1250 How do you know that you've made the right decisions? Have you
1251 picked an interface design that will cause problems later? Have
1252 you picked the most appropriate name? Do you have any questions?
1253
1254 The best way to know for sure, and pick up many helpful suggestions,
1255 is to ask someone who knows. Comp.lang.perl.misc is read by just about
1256 all the people who develop modules and it's the best place to ask.
1257
1258 All you need to do is post a short summary of the module, its
1259 purpose and interfaces. A few lines on each of the main methods is
1260 probably enough. (If you post the whole module it might be ignored
1261 by busy people - generally the very people you want to read it!)
1262
1263 Don't worry about posting if you can't say when the module will be
1264 ready - just say so in the message. It might be worth inviting
1265 others to help you, they may be able to complete it for you!
1266
1267 =item  *
1268
1269 README and other Additional Files.
1270
1271 It's well known that software developers usually fully document the
1272 software they write. If, however, the world is in urgent need of
1273 your software and there is not enough time to write the full
1274 documentation please at least provide a README file containing:
1275
1276 =over 10
1277
1278 =item *
1279
1280 A description of the module/package/extension etc.
1281
1282 =item *
1283
1284 A copyright notice - see below.
1285
1286 =item *
1287
1288 Prerequisites - what else you may need to have.
1289
1290 =item *
1291
1292 How to build it - possible changes to Makefile.PL etc.
1293
1294 =item *
1295
1296 How to install it.
1297
1298 =item *
1299
1300 Recent changes in this release, especially incompatibilities
1301
1302 =item *
1303
1304 Changes / enhancements you plan to make in the future.
1305
1306 =back
1307
1308 If the README file seems to be getting too large you may wish to
1309 split out some of the sections into separate files: INSTALL,
1310 Copying, ToDo etc.
1311
1312 =over 4
1313
1314 =item *
1315
1316 Adding a Copyright Notice.
1317
1318 How you choose to license your work is a personal decision.
1319 The general mechanism is to assert your Copyright and then make
1320 a declaration of how others may copy/use/modify your work.
1321
1322 Perl, for example, is supplied with two types of licence: The GNU GPL
1323 and The Artistic Licence (see the files README, Copying, and Artistic,
1324 or L<perlgpl> and L<perlartistic>).  Larry has good reasons for NOT
1325 just using the GNU GPL.
1326
1327 My personal recommendation, out of respect for Larry, Perl, and the
1328 Perl community at large is to state something simply like:
1329
1330  Copyright (c) 1995 Your Name. All rights reserved.
1331  This program is free software; you can redistribute it and/or
1332  modify it under the same terms as Perl itself.
1333
1334 This statement should at least appear in the README file. You may
1335 also wish to include it in a Copying file and your source files.
1336 Remember to include the other words in addition to the Copyright.
1337
1338 =item  *
1339
1340 Give the module a version/issue/release number.
1341
1342 To be fully compatible with the Exporter and MakeMaker modules you
1343 should store your module's version number in a non-my package
1344 variable called $VERSION.  This should be a positive floating point
1345 number with at least two digits after the decimal (i.e., hundredths,
1346 e.g, C<$VERSION = "0.01">).  Don't use a "1.3.2" style version.
1347 See L<Exporter> for details.
1348
1349 It may be handy to add a function or method to retrieve the number.
1350 Use the number in announcements and archive file names when
1351 releasing the module (ModuleName-1.02.tar.Z).
1352 See perldoc ExtUtils::MakeMaker.pm for details.
1353
1354 =item  *
1355
1356 How to release and distribute a module.
1357
1358 It's good idea to post an announcement of the availability of your
1359 module (or the module itself if small) to the comp.lang.perl.announce
1360 Usenet newsgroup.  This will at least ensure very wide once-off
1361 distribution.
1362
1363 If possible, register the module with CPAN.  You should
1364 include details of its location in your announcement.
1365
1366 Some notes about ftp archives: Please use a long descriptive file
1367 name that includes the version number. Most incoming directories
1368 will not be readable/listable, i.e., you won't be able to see your
1369 file after uploading it. Remember to send your email notification
1370 message as soon as possible after uploading else your file may get
1371 deleted automatically. Allow time for the file to be processed
1372 and/or check the file has been processed before announcing its
1373 location.
1374
1375 FTP Archives for Perl Modules:
1376
1377 Follow the instructions and links on:
1378
1379    http://www.cpan.org/modules/00modlist.long.html
1380    http://www.cpan.org/modules/04pause.html
1381
1382 or upload to one of these sites:
1383
1384    https://pause.kbx.de/pause/
1385    http://pause.perl.org/
1386
1387 and notify <modules@perl.org>.
1388
1389 By using the WWW interface you can ask the Upload Server to mirror
1390 your modules from your ftp or WWW site into your own directory on
1391 CPAN!
1392
1393 Please remember to send me an updated entry for the Module list!
1394
1395 =item  *
1396
1397 Take care when changing a released module.
1398
1399 Always strive to remain compatible with previous released versions.
1400 Otherwise try to add a mechanism to revert to the
1401 old behavior if people rely on it.  Document incompatible changes.
1402
1403 =back
1404
1405 =back
1406
1407 =head2 Guidelines for Converting Perl 4 Library Scripts into Modules
1408
1409 =over 4
1410
1411 =item  *
1412
1413 There is no requirement to convert anything.
1414
1415 If it ain't broke, don't fix it! Perl 4 library scripts should
1416 continue to work with no problems. You may need to make some minor
1417 changes (like escaping non-array @'s in double quoted strings) but
1418 there is no need to convert a .pl file into a Module for just that.
1419
1420 =item  *
1421
1422 Consider the implications.
1423
1424 All Perl applications that make use of the script will need to
1425 be changed (slightly) if the script is converted into a module.  Is
1426 it worth it unless you plan to make other changes at the same time?
1427
1428 =item  *
1429
1430 Make the most of the opportunity.
1431
1432 If you are going to convert the script to a module you can use the
1433 opportunity to redesign the interface.  The guidelines for module
1434 creation above include many of the issues you should consider.
1435
1436 =item  *
1437
1438 The pl2pm utility will get you started.
1439
1440 This utility will read *.pl files (given as parameters) and write
1441 corresponding *.pm files. The pl2pm utilities does the following:
1442
1443 =over 10
1444
1445 =item *
1446
1447 Adds the standard Module prologue lines
1448
1449 =item *
1450
1451 Converts package specifiers from ' to ::
1452
1453 =item *
1454
1455 Converts die(...) to croak(...)
1456
1457 =item *
1458
1459 Several other minor changes
1460
1461 =back
1462
1463 Being a mechanical process pl2pm is not bullet proof. The converted
1464 code will need careful checking, especially any package statements.
1465 Don't delete the original .pl file till the new .pm one works!
1466
1467 =back
1468
1469 =head2 Guidelines for Reusing Application Code
1470
1471 =over 4
1472
1473 =item  *
1474
1475 Complete applications rarely belong in the Perl Module Library.
1476
1477 =item  *
1478
1479 Many applications contain some Perl code that could be reused.
1480
1481 Help save the world! Share your code in a form that makes it easy
1482 to reuse.
1483
1484 =item  *
1485
1486 Break-out the reusable code into one or more separate module files.
1487
1488 =item  *
1489
1490 Take the opportunity to reconsider and redesign the interfaces.
1491
1492 =item  *
1493
1494 In some cases the 'application' can then be reduced to a small
1495
1496 fragment of code built on top of the reusable modules. In these cases
1497 the application could invoked as:
1498
1499      % perl -e 'use Module::Name; method(@ARGV)' ...
1500 or
1501      % perl -mModule::Name ...    (in perl5.002 or higher)
1502
1503 =back
1504
1505 =head1 NOTE
1506
1507 Perl does not enforce private and public parts of its modules as you may
1508 have been used to in other languages like C++, Ada, or Modula-17.  Perl
1509 doesn't have an infatuation with enforced privacy.  It would prefer
1510 that you stayed out of its living room because you weren't invited, not
1511 because it has a shotgun.
1512
1513 The module and its user have a contract, part of which is common law,
1514 and part of which is "written".  Part of the common law contract is
1515 that a module doesn't pollute any namespace it wasn't asked to.  The
1516 written contract for the module (A.K.A. documentation) may make other
1517 provisions.  But then you know when you C<use RedefineTheWorld> that
1518 you're redefining the world and willing to take the consequences.
1519
1520 =cut
1521
1522 read_only_bottom_close_and_rename($out);