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