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