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