This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add autogeneration of perlmodlib.pod and the new perlnewmod.pod,
[perl5.git] / pod / perlmodlib.PL
CommitLineData
2e1d04bc
JH
1#!../miniperl
2
3open (OUT, ">perlmodlib.tmp") or die $!;
4my (@pragma, @mod);
5open (MANIFEST, "../MANIFEST") or die $!;
6
7while (<MANIFEST>) {
8 my $filename;
9 next unless s|^lib/|| or m|^ext/|;
10 ($filename) = /(\S+)/;
11 $filename =~ s|^[^/]+/|| if $filename =~ s|^ext/||;
12 next unless $filename =~ /\.pm$/;
13 next unless open (MOD, "../lib/$filename");
14 my ($name, $thing);
15 my $foundit=0;
16 {local $/="";
17 while (<MOD>) {
18 next unless /^=head1 NAME/;
19 $foundit++;
20 last;
21 }
22 }
23 next unless $foundit;
24 my $title = <MOD>;
25 chomp($title);
26 close MOD;
27
28 my $perlname = $filename;
29 $perlname =~ s|\.pm$||;
30 $perlname =~ s|/|::|g;
31
32 ($name, $thing) = split / - /, $title,2;
33 next unless $name and $thing;
34 $thing=~s/^perl pragma to //i;
35 $thing=ucfirst($thing);
36 $title = "=item $perlname\n\n$thing\n\n";
37
38 if ($filename=~/[A-Z]/) {
39 push @mod, $title;
40 } else {
41 push @pragma, $title;
42 }
43}
44
45print OUT <<'EOF';
46=head1 NAME
47
48perlmodlib - constructing new Perl modules and finding existing ones
49
50=head1 DESCRIPTION
51
52=head1 THE PERL MODULE LIBRARY
53
54Many modules are included the Perl distribution. These are described
55below, and all end in F<.pm>. You may discover compiled library
56file (usually ending in F<.so>) or small pieces of modules to be
57autoloaded (ending in F<.al>); these were automatically generated
58by the installation process. You may also discover files in the
59library directory that end in either F<.pl> or F<.ph>. These are
60old libraries supplied so that old programs that use them still
61run. The F<.pl> files will all eventually be converted into standard
62modules, and the F<.ph> files made by B<h2ph> will probably end up
63as extension modules made by B<h2xs>. (Some F<.ph> values may
64already be available through the POSIX, Errno, or Fcntl modules.)
65The B<pl2pm> file in the distribution may help in your conversion,
66but it's just a mechanical process and therefore far from bulletproof.
67
68=head2 Pragmatic Modules
69
70They work somewhat like compiler directives (pragmata) in that they
71tend to affect the compilation of your program, and thus will usually
72work well only when used within a C<use>, or C<no>. Most of these
73are lexically scoped, so an inner BLOCK may countermand them
74by saying:
75
76 no integer;
77 no strict 'refs';
78 no warnings;
79
80which lasts until the end of that BLOCK.
81
82Some pragmas are lexically scoped--typically those that affect the
83C<$^H> hints variable. Others affect the current package instead,
84like C<use vars> and C<use subs>, which allow you to predeclare a
85variables or subroutines within a particular I<file> rather than
86just a block. Such declarations are effective for the entire file
87for which they were declared. You cannot rescind them with C<no
88vars> or C<no subs>.
89
90The following pragmas are defined (and have their own documentation).
91
92=over 12
93
94EOF
95
96print OUT $_ for (sort @pragma);
97
98print OUT <<EOF;
99=back
100
101=head2 Standard Modules
102
103Standard, bundled modules are all expected to behave in a well-defined
104manner with respect to namespace pollution because they use the
105Exporter module. See their own documentation for details.
106
107=over 12
108
109EOF
110
111print OUT $_ for (sort @mod);
112
113print OUT <<'EOF';
114=back
115
116To find out I<all> modules installed on your system, including
117those without documentation or outside the standard release,
118jus tdo this:
119
120 % find `perl -e 'print "@INC"'` -name '*.pm' -print
121
122They should all have their own documentation installed and accessible
123via your system man(1) command. If you do not have a B<find>
124program, you can use the Perl B<find2perl> program instead, which
125generates Perl code as output you can run through perl. If you
126have a B<man> program but it doesn't find your modules, you'll have
127to fix your manpath. See L<perl> for details. If you have no
128system B<man> command, you might try the B<perldoc> program.
129
130=head2 Extension Modules
131
132Extension modules are written in C (or a mix of Perl and C). They
133are usually dynamically loaded into Perl if and when you need them,
134but may also be be linked in statically. Supported extension modules
135include Socket, Fcntl, and POSIX.
136
137Many popular C extension modules do not come bundled (at least, not
138completely) due to their sizes, volatility, or simply lack of time
139for adequate testing and configuration across the multitude of
140platforms on which Perl was beta-tested. You are encouraged to
141look for them on CPAN (described below), or using web search engines
142like Alta Vista or Deja News.
143
144=head1 CPAN
145
146CPAN stands for Comprehensive Perl Archive Network; it's a globally
147replicated trove of Perl materials, including documentation, style
148guides, tricks and traps, alternate ports to non-Unix systems and
149occasional binary distributions for these. Search engines for
150CPAN can be found at http://cpan.perl.com/ and at
151http://theory.uwinnipeg.ca/mod_perl/cpan-search.pl .
152
153Most importantly, CPAN includes around a thousand unbundled modules,
154some of which require a C compiler to build. Major categories of
155modules are:
156
157=over
158
159=item *
160Language Extensions and Documentation Tools
161
162=item *
163Development Support
164
165=item *
166Operating System Interfaces
167
168=item *
169Networking, Device Control (modems) and InterProcess Communication
170
171=item *
172Data Types and Data Type Utilities
173
174=item *
175Database Interfaces
176
177=item *
178User Interfaces
179
180=item *
181Interfaces to / Emulations of Other Programming Languages
182
183=item *
184File Names, File Systems and File Locking (see also File Handles)
185
186=item *
187String Processing, Language Text Processing, Parsing, and Searching
188
189=item *
190Option, Argument, Parameter, and Configuration File Processing
191
192=item *
193Internationalization and Locale
194
195=item *
196Authentication, Security, and Encryption
197
198=item *
199World Wide Web, HTML, HTTP, CGI, MIME
200
201=item *
202Server and Daemon Utilities
203
204=item *
205Archiving and Compression
206
207=item *
208Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
209
210=item *
211Mail and Usenet News
212
213=item *
214Control Flow Utilities (callbacks and exceptions etc)
215
216=item *
217File Handle and Input/Output Stream Utilities
218
219=item *
220Miscellaneous Modules
221
222=back
223
224Registered CPAN sites as of this writing include the following.
225You should try to choose one close to you:
226
227=over
228
229=item Africa
230
231 South Africa ftp://ftp.is.co.za/programming/perl/CPAN/
232 ftp://ftp.saix.net/pub/CPAN/
233 ftp://ftp.sun.ac.za/CPAN/
234 ftp://ftpza.co.za/pub/mirrors/cpan/
235
236
237=item Asia
238
239 China ftp://freesoft.cei.gov.cn/pub/languages/perl/CPAN/
240 Hong Kong ftp://ftp.pacific.net.hk/pub/mirror/CPAN/
241 Indonesia ftp://malone.piksi.itb.ac.id/pub/CPAN/
242 Israel ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
243 Japan ftp://ftp.dti.ad.jp/pub/lang/CPAN/
244 ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
245 ftp://ftp.lab.kdd.co.jp/lang/perl/CPAN/
246 ftp://ftp.meisei-u.ac.jp/pub/CPAN/
247 ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
248 ftp://mirror.nucba.ac.jp/mirror/Perl/
249 Saudi-Arabia ftp://ftp.isu.net.sa/pub/CPAN/
250 Singapore ftp://ftp.nus.edu.sg/pub/unix/perl/CPAN/
251 South Korea ftp://ftp.bora.net/pub/CPAN/
252 ftp://ftp.kornet.net/pub/CPAN/
253 ftp://ftp.nuri.net/pub/CPAN/
254 Taiwan ftp://coda.nctu.edu.tw/computer-languages/perl/CPAN/
255 ftp://ftp.ee.ncku.edu.tw/pub3/perl/CPAN/
256 ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
257 Thailand ftp://ftp.nectec.or.th/pub/mirrors/CPAN/
258
259
260=item Australasia
261
262 Australia ftp://cpan.topend.com.au/pub/CPAN/
263 ftp://ftp.labyrinth.net.au/pub/perl-CPAN/
264 ftp://ftp.sage-au.org.au/pub/compilers/perl/CPAN/
265 ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
266 New Zealand ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
267 ftp://sunsite.net.nz/pub/languages/perl/CPAN/
268
269
270=item Central America
271
272 Costa Rica ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
273
274
275=item Europe
276
277 Austria ftp://ftp.tuwien.ac.at/pub/languages/perl/CPAN/
278 Belgium ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
279 Bulgaria ftp://ftp.ntrl.net/pub/mirrors/CPAN/
280 Croatia ftp://ftp.linux.hr/pub/CPAN/
281 Czech Republic ftp://ftp.fi.muni.cz/pub/perl/
282 ftp://sunsite.mff.cuni.cz/Languages/Perl/CPAN/
283 Denmark ftp://sunsite.auc.dk/pub/languages/perl/CPAN/
284 Estonia ftp://ftp.ut.ee/pub/languages/perl/CPAN/
285 Finland ftp://ftp.funet.fi/pub/languages/perl/CPAN/
286 France ftp://ftp.grolier.fr/pub/perl/CPAN/
287 ftp://ftp.lip6.fr/pub/perl/CPAN/
288 ftp://ftp.oleane.net/pub/mirrors/CPAN/
289 ftp://ftp.pasteur.fr/pub/computing/CPAN/
290 ftp://ftp.uvsq.fr/pub/perl/CPAN/
291 German ftp://ftp.gigabell.net/pub/CPAN/
292 Germany ftp://ftp.archive.de.uu.net/pub/CPAN/
293 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/
294 ftp://ftp.gmd.de/packages/CPAN/
295 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
296
297ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
298 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
299 ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
300 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
301 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
302 Germany ftp://ftp.archive.de.uu.net/pub/CPAN/
303 ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/
304 ftp://ftp.gmd.de/packages/CPAN/
305 ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
306
307ftp://ftp.leo.org/pub/comp/general/programming/languages/script/perl/CPAN/
308 ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
309 ftp://ftp.rz.ruhr-uni-bochum.de/pub/CPAN/
310 ftp://ftp.uni-erlangen.de/pub/source/CPAN/
311 ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
312 Greece ftp://ftp.ntua.gr/pub/lang/perl/
313 Hungary ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
314 Iceland ftp://ftp.gm.is/pub/CPAN/
315 Ireland ftp://cpan.indigo.ie/pub/CPAN/
316 ftp://sunsite.compapp.dcu.ie/pub/perl/
317 Italy ftp://cis.uniRoma2.it/CPAN/
318 ftp://ftp.flashnet.it/pub/CPAN/
319 ftp://ftp.unina.it/pub/Other/CPAN/
320 ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
321 Netherlands ftp://ftp.cs.uu.nl/mirror/CPAN/
322 ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
323 Norway ftp://ftp.uit.no/pub/languages/perl/cpan/
324 ftp://sunsite.uio.no/pub/languages/perl/CPAN/
325 Poland ftp://ftp.man.torun.pl/pub/CPAN/
326 ftp://ftp.pk.edu.pl/pub/lang/perl/CPAN/
327 ftp://sunsite.icm.edu.pl/pub/CPAN/
328 Portugal ftp://ftp.ci.uminho.pt/pub/mirrors/cpan/
329 ftp://ftp.ist.utl.pt/pub/CPAN/
330 ftp://ftp.ua.pt/pub/CPAN/
331 Romania ftp://ftp.dnttm.ro/pub/CPAN/
332 Russia ftp://ftp.chg.ru/pub/lang/perl/CPAN/
333 ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
334 Slovakia ftp://ftp.entry.sk/pub/languages/perl/CPAN/
335 Slovenia ftp://ftp.arnes.si/software/perl/CPAN/
336 Spain ftp://ftp.etse.urv.es/pub/perl/
337 ftp://ftp.rediris.es/mirror/CPAN/
338 Sweden ftp://ftp.sunet.se/pub/lang/perl/CPAN/
339 Switzerland ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
340 Turkey ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
341 United Kingdom ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
342 ftp://ftp.flirble.org/pub/languages/perl/CPAN/
343
344ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
345 ftp://ftp.plig.org/pub/CPAN/
346 ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
347
348
349=item North America
350
351 Alberta ftp://sunsite.ualberta.ca/pub/Mirror/CPAN/
352 California ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
353 ftp://cpan.valueclick.com/CPAN/
354 ftp://ftp.cdrom.com/pub/perl/CPAN/
355 http://download.sourceforge.net/mirrors/CPAN/
356 Colorado ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
357 Florida ftp://ftp.cise.ufl.edu/pub/perl/CPAN/
358 Georgia ftp://ftp.twoguys.org/CPAN/
359 Illinois ftp://uiarchive.uiuc.edu/pub/lang/perl/CPAN/
360 Indiana ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN/
361 ftp://ftp.uwsg.indiana.edu/pub/perl/CPAN/
362 Kentucky ftp://ftp.uky.edu/CPAN/
363 Manitoba ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
364 Massachusetts
365ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
366 ftp://ftp.iguide.com/pub/mirrors/packages/perl/CPAN/
367 Mexico ftp://ftp.msg.com.mx/pub/CPAN/
368 New York ftp://ftp.deao.net/pub/CPAN/
369 ftp://ftp.rge.com/pub/languages/perl/
370 North Carolina ftp://ftp.duke.edu/pub/perl/
371 Nova Scotia ftp://cpan.chebucto.ns.ca/pub/CPAN/
372 Oklahoma ftp://ftp.ou.edu/mirrors/CPAN/
373 Ontario ftp://ftp.crc.ca/pub/packages/lang/perl/CPAN/
374 Oregon ftp://ftp.orst.edu/pub/packages/CPAN/
375 Pennsylvania ftp://ftp.epix.net/pub/languages/perl/
376 Tennessee ftp://ftp.sunsite.utk.edu/pub/CPAN/
377 Texas ftp://ftp.sedl.org/pub/mirrors/CPAN/
378 ftp://jhcloos.com/pub/mirror/CPAN/
379 Utah ftp://mirror.xmission.com/CPAN/
380 Virginia ftp://ftp.perl.org/pub/perl/CPAN/
381 ftp://ruff.cs.jmu.edu/pub/CPAN/
382 Washington ftp://ftp-mirror.internap.com/pub/CPAN/
383 ftp://ftp.llarian.net/pub/CPAN/
384 ftp://ftp.spu.edu/pub/CPAN/
385
386
387=item South America
388
389 Brazil ftp://cpan.if.usp.br/pub/mirror/CPAN/
390 ftp://ftp.matrix.com.br/pub/perl/
391 Chile ftp://sunsite.dcc.uchile.cl/pub/Lang/PERL/
392
393=back
394
395For an up-to-date listing of CPAN sites,
396see http://www.perl.com/perl/CPAN/SITES or ftp://www.perl.com/CPAN/SITES .
397
398=head1 Modules: Creation, Use, and Abuse
399
400(The following section is borrowed directly from Tim Bunce's modules
401file, available at your nearest CPAN site.)
402
403Perl implements a class using a package, but the presence of a
404package doesn't imply the presence of a class. A package is just a
405namespace. A class is a package that provides subroutines that can be
406used as methods. A method is just a subroutine that expects, as its
407first argument, either the name of a package (for "static" methods),
408or a reference to something (for "virtual" methods).
409
410A module is a file that (by convention) provides a class of the same
411name (sans the .pm), plus an import method in that class that can be
412called to fetch exported symbols. This module may implement some of
413its methods by loading dynamic C or C++ objects, but that should be
414totally transparent to the user of the module. Likewise, the module
415might set up an AUTOLOAD function to slurp in subroutine definitions on
416demand, but this is also transparent. Only the F<.pm> file is required to
417exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
418the AUTOLOAD mechanism.
419
420=head2 Guidelines for Module Creation
421
422=over 4
423
424=item Do similar modules already exist in some form?
425
426If so, please try to reuse the existing modules either in whole or
427by inheriting useful features into a new class. If this is not
428practical try to get together with the module authors to work on
429extending or enhancing the functionality of the existing modules.
430A perfect example is the plethora of packages in perl4 for dealing
431with command line options.
432
433If you are writing a module to expand an already existing set of
434modules, please coordinate with the author of the package. It
435helps if you follow the same naming scheme and module interaction
436scheme as the original author.
437
438=item Try to design the new module to be easy to extend and reuse.
439
440Try to C<use warnings;> (or C<use warnings qw(...);>).
441Remember that you can add C<no warnings qw(...);> to individual blocks
442of code that need less warnings.
443
444Use blessed references. Use the two argument form of bless to bless
445into the class name given as the first parameter of the constructor,
446e.g.,:
447
448 sub new {
449 my $class = shift;
450 return bless {}, $class;
451 }
452
453or even this if you'd like it to be used as either a static
454or a virtual method.
455
456 sub new {
457 my $self = shift;
458 my $class = ref($self) || $self;
459 return bless {}, $class;
460 }
461
462Pass arrays as references so more parameters can be added later
463(it's also faster). Convert functions into methods where
464appropriate. Split large methods into smaller more flexible ones.
465Inherit methods from other modules if appropriate.
466
467Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
468Generally you can delete the C<eq 'FOO'> part with no harm at all.
469Let the objects look after themselves! Generally, avoid hard-wired
470class names as far as possible.
471
472Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
473C<< $r->func() >> would work (see L<perlbot> for more details).
474
475Use autosplit so little used or newly added functions won't be a
476burden to programs that don't use them. Add test functions to
477the module after __END__ either using AutoSplit or by saying:
478
479 eval join('',<main::DATA>) || die $@ unless caller();
480
481Does your module pass the 'empty subclass' test? If you say
482C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
483to use SUBCLASS in exactly the same way as YOURCLASS. For example,
484does your application still work if you change: C<$obj = new YOURCLASS;>
485into: C<$obj = new SUBCLASS;> ?
486
487Avoid keeping any state information in your packages. It makes it
488difficult for multiple other packages to use yours. Keep state
489information in objects.
490
491Always use B<-w>.
492
493Try to C<use strict;> (or C<use strict qw(...);>).
494Remember that you can add C<no strict qw(...);> to individual blocks
495of code that need less strictness.
496
497Always use B<-w>.
498
499Follow the guidelines in the perlstyle(1) manual.
500
501Always use B<-w>.
502
503=item Some simple style guidelines
504
505The perlstyle manual supplied with Perl has many helpful points.
506
507Coding style is a matter of personal taste. Many people evolve their
508style over several years as they learn what helps them write and
509maintain good code. Here's one set of assorted suggestions that
510seem to be widely used by experienced developers:
511
512Use underscores to separate words. It is generally easier to read
513$var_names_like_this than $VarNamesLikeThis, especially for
514non-native speakers of English. It's also a simple rule that works
515consistently with VAR_NAMES_LIKE_THIS.
516
517Package/Module names are an exception to this rule. Perl informally
518reserves lowercase module names for 'pragma' modules like integer
519and strict. Other modules normally begin with a capital letter and
520use mixed case with no underscores (need to be short and portable).
521
522You may find it helpful to use letter case to indicate the scope
523or nature of a variable. For example:
524
525 $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
526 $Some_Caps_Here package-wide global/static
527 $no_caps_here function scope my() or local() variables
528
529Function and method names seem to work best as all lowercase.
530e.g., C<< $obj->as_string() >>.
531
532You can use a leading underscore to indicate that a variable or
533function should not be used outside the package that defined it.
534
535=item Select what to export.
536
537Do NOT export method names!
538
539Do NOT export anything else by default without a good reason!
540
541Exports pollute the namespace of the module user. If you must
542export try to use @EXPORT_OK in preference to @EXPORT and avoid
543short or common names to reduce the risk of name clashes.
544
545Generally anything not exported is still accessible from outside the
546module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
547syntax. By convention you can use a leading underscore on names to
548indicate informally that they are 'internal' and not for public use.
549
550(It is actually possible to get private functions by saying:
551C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
552directly as a method, because a method must have a name in the symbol
553table.)
554
555As a general rule, if the module is trying to be object oriented
556then export nothing. If it's just a collection of functions then
557@EXPORT_OK anything but use @EXPORT with caution.
558
559=item Select a name for the module.
560
561This name should be as descriptive, accurate, and complete as
562possible. Avoid any risk of ambiguity. Always try to use two or
563more whole words. Generally the name should reflect what is special
564about what the module does rather than how it does it. Please use
565nested module names to group informally or categorize a module.
566There should be a very good reason for a module not to have a nested name.
567Module names should begin with a capital letter.
568
569Having 57 modules all called Sort will not make life easy for anyone
570(though having 23 called Sort::Quick is only marginally better :-).
571Imagine someone trying to install your module alongside many others.
572If in any doubt ask for suggestions in comp.lang.perl.misc.
573
574If you are developing a suite of related modules/classes it's good
575practice to use nested classes with a common prefix as this will
576avoid namespace clashes. For example: Xyz::Control, Xyz::View,
577Xyz::Model etc. Use the modules in this list as a naming guide.
578
579If adding a new module to a set, follow the original author's
580standards for naming modules and the interface to methods in
581those modules.
582
583To be portable each component of a module name should be limited to
58411 characters. If it might be used on MS-DOS then try to ensure each is
585unique in the first 8 characters. Nested modules make this easier.
586
587=item Have you got it right?
588
589How do you know that you've made the right decisions? Have you
590picked an interface design that will cause problems later? Have
591you picked the most appropriate name? Do you have any questions?
592
593The best way to know for sure, and pick up many helpful suggestions,
594is to ask someone who knows. Comp.lang.perl.misc is read by just about
595all the people who develop modules and it's the best place to ask.
596
597All you need to do is post a short summary of the module, its
598purpose and interfaces. A few lines on each of the main methods is
599probably enough. (If you post the whole module it might be ignored
600by busy people - generally the very people you want to read it!)
601
602Don't worry about posting if you can't say when the module will be
603ready - just say so in the message. It might be worth inviting
604others to help you, they may be able to complete it for you!
605
606=item README and other Additional Files.
607
608It's well known that software developers usually fully document the
609software they write. If, however, the world is in urgent need of
610your software and there is not enough time to write the full
611documentation please at least provide a README file containing:
612
613=over 10
614
615=item *
616A description of the module/package/extension etc.
617
618=item *
619A copyright notice - see below.
620
621=item *
622Prerequisites - what else you may need to have.
623
624=item *
625How to build it - possible changes to Makefile.PL etc.
626
627=item *
628How to install it.
629
630=item *
631Recent changes in this release, especially incompatibilities
632
633=item *
634Changes / enhancements you plan to make in the future.
635
636=back
637
638If the README file seems to be getting too large you may wish to
639split out some of the sections into separate files: INSTALL,
640Copying, ToDo etc.
641
642=over 4
643
644=item Adding a Copyright Notice.
645
646How you choose to license your work is a personal decision.
647The general mechanism is to assert your Copyright and then make
648a declaration of how others may copy/use/modify your work.
649
650Perl, for example, is supplied with two types of licence: The GNU
651GPL and The Artistic Licence (see the files README, Copying, and
652Artistic). Larry has good reasons for NOT just using the GNU GPL.
653
654My personal recommendation, out of respect for Larry, Perl, and the
655Perl community at large is to state something simply like:
656
657 Copyright (c) 1995 Your Name. All rights reserved.
658 This program is free software; you can redistribute it and/or
659 modify it under the same terms as Perl itself.
660
661This statement should at least appear in the README file. You may
662also wish to include it in a Copying file and your source files.
663Remember to include the other words in addition to the Copyright.
664
665=item Give the module a version/issue/release number.
666
667To be fully compatible with the Exporter and MakeMaker modules you
668should store your module's version number in a non-my package
669variable called $VERSION. This should be a floating point
670number with at least two digits after the decimal (i.e., hundredths,
671e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
672See L<Exporter> for details.
673
674It may be handy to add a function or method to retrieve the number.
675Use the number in announcements and archive file names when
676releasing the module (ModuleName-1.02.tar.Z).
677See perldoc ExtUtils::MakeMaker.pm for details.
678
679=item How to release and distribute a module.
680
681It's good idea to post an announcement of the availability of your
682module (or the module itself if small) to the comp.lang.perl.announce
683Usenet newsgroup. This will at least ensure very wide once-off
684distribution.
685
686If possible, register the module with CPAN. You should
687include details of its location in your announcement.
688
689Some notes about ftp archives: Please use a long descriptive file
690name that includes the version number. Most incoming directories
691will not be readable/listable, i.e., you won't be able to see your
692file after uploading it. Remember to send your email notification
693message as soon as possible after uploading else your file may get
694deleted automatically. Allow time for the file to be processed
695and/or check the file has been processed before announcing its
696location.
697
698FTP Archives for Perl Modules:
699
700Follow the instructions and links on:
701
702 http://www.perl.com/CPAN/modules/00modlist.long.html
703 http://www.perl.com/CPAN/modules/04pause.html
704
705or upload to one of these sites:
706
707 https://pause.kbx.de/pause/
708 http://pause.perl.org/pause/
709
710and notify <modules@perl.org>.
711
712By using the WWW interface you can ask the Upload Server to mirror
713your modules from your ftp or WWW site into your own directory on
714CPAN!
715
716Please remember to send me an updated entry for the Module list!
717
718=item Take care when changing a released module.
719
720Always strive to remain compatible with previous released versions.
721Otherwise try to add a mechanism to revert to the
722old behavior if people rely on it. Document incompatible changes.
723
724=back
725
726=back
727
728=head2 Guidelines for Converting Perl 4 Library Scripts into Modules
729
730=over 4
731
732=item There is no requirement to convert anything.
733
734If it ain't broke, don't fix it! Perl 4 library scripts should
735continue to work with no problems. You may need to make some minor
736changes (like escaping non-array @'s in double quoted strings) but
737there is no need to convert a .pl file into a Module for just that.
738
739=item Consider the implications.
740
741All Perl applications that make use of the script will need to
742be changed (slightly) if the script is converted into a module. Is
743it worth it unless you plan to make other changes at the same time?
744
745=item Make the most of the opportunity.
746
747If you are going to convert the script to a module you can use the
748opportunity to redesign the interface. The guidelines for module
749creation above include many of the issues you should consider.
750
751=item The pl2pm utility will get you started.
752
753This utility will read *.pl files (given as parameters) and write
754corresponding *.pm files. The pl2pm utilities does the following:
755
756=over 10
757
758=item *
759Adds the standard Module prologue lines
760
761=item *
762Converts package specifiers from ' to ::
763
764=item *
765Converts die(...) to croak(...)
766
767=item *
768Several other minor changes
769
770=back
771
772Being a mechanical process pl2pm is not bullet proof. The converted
773code will need careful checking, especially any package statements.
774Don't delete the original .pl file till the new .pm one works!
775
776=back
777
778=head2 Guidelines for Reusing Application Code
779
780=over 4
781
782=item Complete applications rarely belong in the Perl Module Library.
783
784=item Many applications contain some Perl code that could be reused.
785
786Help save the world! Share your code in a form that makes it easy
787to reuse.
788
789=item Break-out the reusable code into one or more separate module files.
790
791=item Take the opportunity to reconsider and redesign the interfaces.
792
793=item In some cases the 'application' can then be reduced to a small
794
795fragment of code built on top of the reusable modules. In these cases
796the application could invoked as:
797
798 % perl -e 'use Module::Name; method(@ARGV)' ...
799or
800 % perl -mModule::Name ... (in perl5.002 or higher)
801
802=back
803
804=head1 NOTE
805
806Perl does not enforce private and public parts of its modules as you may
807have been used to in other languages like C++, Ada, or Modula-17. Perl
808doesn't have an infatuation with enforced privacy. It would prefer
809that you stayed out of its living room because you weren't invited, not
810because it has a shotgun.
811
812The module and its user have a contract, part of which is common law,
813and part of which is "written". Part of the common law contract is
814that a module doesn't pollute any namespace it wasn't asked to. The
815written contract for the module (A.K.A. documentation) may make other
816provisions. But then you know when you C<use RedefineTheWorld> that
817you're redefining the world and willing to take the consequences.
818EOF
819
820close MANIFEST or warn "$0: failed to close MANIFEST (../MANIFEST): $!";
821close OUT or warn "$0: failed to close OUT (perlmodlib.tmp): $!";
822