pod/perlmodlib.PL

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