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