pod/perlmodlib.PL

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