perl5.git.perl.org Git - perl5.git/blame_incremental

... / ...

Commit	Line	Data
	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