pod/perlmodlib.PL

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