pod/perlmodlib.PL

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