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