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