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