pod/perlmodlib.PL

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