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