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