pod/perlmodlib.PL

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