pod/perlmodlib.PL

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