From: Nicholas Clark Date: Sat, 13 Jun 2009 10:46:29 +0000 (+0100) Subject: Generate perlmodlib.pod at build time, instead of shipping it. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=6e2c892858f0153d478baaafedb3170a7306bd0a;p=p5sagit%2Fp5-mst-13.2.git Generate perlmodlib.pod at build time, instead of shipping it. --- diff --git a/MANIFEST b/MANIFEST index 48ab18c..ead080d 100644 --- a/MANIFEST +++ b/MANIFEST @@ -3636,7 +3636,6 @@ pod/perllocale.pod Perl locale support pod/perllol.pod Perl data structures: arrays of arrays pod/perlmodinstall.pod Perl modules: how to install from CPAN pod/perlmodlib.PL Generate pod/perlmodlib.pod -pod/perlmodlib.pod Perl modules: how to write and use pod/perlmod.pod Perl modules: how they work pod/perlmodstyle.pod Perl modules: how to write modules with style pod/perlnewmod.pod Perl modules: preparing a new module for distribution diff --git a/Makefile.SH b/Makefile.SH index c78aefc..4afaf88 100644 --- a/Makefile.SH +++ b/Makefile.SH @@ -462,7 +462,7 @@ mini_obj = $(obj1) $(obj2) $(obj3) $(ARCHOBJS) ndt_obj = $(obj0) $(obj1) $(obj2) $(obj3) $(ARCHOBJS) obj = $(ndt_obj) $(DTRACE_O) -perltoc_pod_prereqs = extra.pods pod/perlapi.pod pod/perldelta.pod pod/perlintern.pod +perltoc_pod_prereqs = extra.pods pod/perlapi.pod pod/perldelta.pod pod/perlintern.pod pod/perlmodlib.pod generated_pods = pod/perltoc.pod $(perltoc_pod_prereqs) lintflags = \ @@ -989,6 +989,9 @@ pod/perltoc.pod: $(perltoc_pod_prereqs) perl$(EXE_EXT) $(ext) pod/buildtoc pod/perlapi.pod pod/perlintern.pod: miniperl$(EXE_EXT) autodoc.pl embed.fnc $(LDLIBPTH) $(RUN) ./miniperl$(EXE_EXT) -Ilib autodoc.pl +pod/perlmodlib.pod: miniperl$(EXE_EXT) pod/perlmodlib.PL MANIFEST + $(LDLIBPTH) $(RUN) ./miniperl$(EXE_EXT) -Ilib pod/perlmodlib.PL -q + pod/perldelta.pod: pod/perl5110delta.pod $(LNS) perl5110delta.pod pod/perldelta.pod diff --git a/pod.lst b/pod.lst index 548b1b7..0a4a1e8 100644 --- a/pod.lst +++ b/pod.lst @@ -89,7 +89,7 @@ h Reference Manual perlsec Perl security perlmod Perl modules: how they work - perlmodlib Perl modules: how to write and use +g perlmodlib Perl modules: how to write and use perlmodstyle Perl modules: how to write modules with style perlmodinstall Perl modules: how to install from CPAN perlnewmod Perl modules: preparing a new module for distribution diff --git a/pod/perlmodlib.pod b/pod/perlmodlib.pod deleted file mode 100644 index 6a4e715..0000000 --- a/pod/perlmodlib.pod +++ /dev/null @@ -1,3422 +0,0 @@ -=for maintainers -Generated by perlmodlib.PL -- DO NOT EDIT! - -=head1 NAME - -perlmodlib - constructing new Perl modules and finding existing ones - -=head1 THE PERL MODULE LIBRARY - -Many modules are included in the Perl distribution. These are described -below, and all end in F<.pm>. You may discover compiled library -files (usually ending in F<.so>) or small pieces of modules to be -autoloaded (ending in F<.al>); these were automatically generated -by the installation process. You may also discover files in the -library directory that end in either F<.pl> or F<.ph>. These are -old libraries supplied so that old programs that use them still -run. The F<.pl> files will all eventually be converted into standard -modules, and the F<.ph> files made by B will probably end up -as extension modules made by B. (Some F<.ph> values may -already be available through the POSIX, Errno, or Fcntl modules.) -The B file in the distribution may help in your conversion, -but it's just a mechanical process and therefore far from bulletproof. - -=head2 Pragmatic Modules - -They work somewhat like compiler directives (pragmata) in that they -tend to affect the compilation of your program, and thus will usually -work well only when used within a C, or C. Most of these -are lexically scoped, so an inner BLOCK may countermand them -by saying: - - no integer; - no strict 'refs'; - no warnings; - -which lasts until the end of that BLOCK. - -Some pragmas are lexically scoped--typically those that affect the -C<$^H> hints variable. Others affect the current package instead, -like C and C, which allow you to predeclare a -variables or subroutines within a particular I rather than -just a block. Such declarations are effective for the entire file -for which they were declared. You cannot rescind them with C or C. - -The following pragmas are defined (and have their own documentation). - -=over 12 - -=item attributes - -Get/set subroutine or variable attributes - -=item autodie - -Replace functions with ones that succeed or die with lexical scope - -=item autodie::exception - -Exceptions from autodying functions. - -=item autodie::exception::system - -Exceptions from autodying system(). - -=item autouse - -Postpone load of modules until a function is used - -=item base - -Establish an ISA relationship with base classes at compile time - -=item bigint - -Transparent BigInteger support for Perl - -=item bignum - -Transparent BigNumber support for Perl - -=item bigrat - -Transparent BigNumber/BigRational support for Perl - -=item blib - -Use MakeMaker's uninstalled version of a package - -=item bytes - -Force byte semantics rather than character semantics - -=item charnames - -Define character names for C<\N{named}> string literal escapes - -=item constant - -Declare constants - -=item deprecate - -Perl pragma for deprecating the core version of a module - -=item diagnostics - -Produce verbose warning diagnostics - -=item encoding - -Allows you to write your script in non-ascii or non-utf8 - -=item encoding::warnings - -Warn on implicit encoding conversions - -=item feature - -Enable new syntactic features - -=item fields - -Compile-time class fields - -=item filetest - -Control the filetest permission operators - -=item if - -C a Perl module if a condition holds - -=item integer - -Use integer arithmetic instead of floating point - -=item less - -Request less of something - -=item lib - -Manipulate @INC at compile time - -=item locale - -Use and avoid POSIX locales for built-in operations - -=item mro - -Method Resolution Order - -=item open - -Set default PerlIO layers for input and output - -=item ops - -Restrict unsafe operations when compiling - -=item overload - -Package for overloading Perl operations - -=item overloading - -Lexically control overloading - -=item parent - -Establish an ISA relationship with base classes at compile time - -=item re - -Alter regular expression behaviour - -=item sigtrap - -Enable simple signal handling - -=item sort - -Control sort() behaviour - -=item strict - -Restrict unsafe constructs - -=item subs - -Predeclare sub names - -=item threads - -Perl interpreter-based threads - -=item threads::shared - -Perl extension for sharing data structures between threads - -=item utf8 - -Enable/disable UTF-8 (or UTF-EBCDIC) in source code - -=item vars - -Predeclare global variable names (obsolete) - -=item version - -Perl extension for Version Objects - -=item vmsish - -Control VMS-specific language features - -=item warnings - -Control optional warnings - -=item warnings::register - -Warnings import function - -=back - -=head2 Standard Modules - -Standard, bundled modules are all expected to behave in a well-defined -manner with respect to namespace pollution because they use the -Exporter module. See their own documentation for details. - -It's possible that not all modules listed below are installed on your -system. For example, the GDBM_File module will not be installed if you -don't have the gdbm library. - -=over 12 - -=item AnyDBM_File - -Provide framework for multiple DBMs - -=item App::Prove - -Implements the C command. - -=item App::Prove::State - -State storage for the C command. - -=item App::Prove::State::Result - -Individual test suite results. - -=item App::Prove::State::Result::Test - -Individual test results. - -=item Archive::Extract - -A generic archive extracting mechanism - -=item Archive::Tar - -Module for manipulations of tar archives - -=item Archive::Tar::File - -A subclass for in-memory extracted file from Archive::Tar - -=item Attribute::Handlers - -Simpler definition of attribute handlers - -=item AutoLoader - -Load subroutines only on demand - -=item AutoSplit - -Split a package for autoloading - -=item B - -The Perl Compiler - -=item B::Concise - -Walk Perl syntax tree, printing concise info about ops - -=item B::Debug - -Walk Perl syntax tree, printing debug info about ops - -=item B::Deparse - -Perl compiler backend to produce perl code - -=item B::Lint - -Perl lint - -=item B::Lint::Debug - -Adds debugging stringification to B:: - -=item B::Showlex - -Show lexical variables used in functions or files - -=item B::Terse - -Walk Perl syntax tree, printing terse info about ops - -=item B::Xref - -Generates cross reference reports for Perl programs - -=item Benchmark - -Benchmark running times of Perl code - -=item CGI - -Handle Common Gateway Interface requests and responses - -=item CGI::Apache - -Backward compatibility module for CGI.pm - -=item CGI::Carp - -CGI routines for writing to the HTTPD (or other) error log - -=item CGI::Cookie - -Interface to Netscape Cookies - -=item CGI::Fast - -CGI Interface for Fast CGI - -=item CGI::Pretty - -Module to produce nicely formatted HTML code - -=item CGI::Push - -Simple Interface to Server Push - -=item CGI::Switch - -Backward compatibility module for defunct CGI::Switch - -=item CGI::Util - -Internal utilities used by CGI module - -=item CORE - -Pseudo-namespace for Perl's core routines - -=item CPAN - -Query, download and build perl modules from CPAN sites - -=item CPAN::API::HOWTO - -A recipe book for programming with CPAN.pm - -=item CPAN::Distroprefs - -Read and match distroprefs - -=item CPAN::FirstTime - -Utility for CPAN::Config file Initialization - -=item CPAN::Kwalify - -Interface between CPAN.pm and Kwalify.pm - -=item CPAN::Nox - -Wrapper around CPAN.pm without using any XS module - -=item CPAN::Version - -Utility functions to compare CPAN versions - -=item CPANPLUS - -API & CLI access to the CPAN mirrors - -=item CPANPLUS::Dist::Base - -Base class for custom distribution classes - -=item CPANPLUS::Dist::Build - -CPANPLUS plugin to install packages that use Build.PL - -=item CPANPLUS::Dist::Build::Constants - -Constants for CPANPLUS::Dist::Build - -=item CPANPLUS::Dist::Sample - -Sample code to create your own Dist::* plugin - -=item CPANPLUS::Internals::Source::Memory - -In memory implementation - -=item CPANPLUS::Internals::Source::SQLite - -SQLite implementation - -=item CPANPLUS::Shell::Classic - -CPAN.pm emulation for CPANPLUS - -=item CPANPLUS::Shell::Default::Plugins::HOWTO - -Documentation on how to write your own plugins - -=item Carp - -Warn of errors (from perspective of caller) - -=item Carp::Heavy - -Heavy machinery, no user serviceable parts inside - -=item Class::ISA - -Report the search path for a class's ISA tree - -=item Class::Struct - -Declare struct-like datatypes as Perl classes - -=item Compress::Raw::Bzip2 - -Low-Level Interface to bzip2 compression library - -=item Compress::Raw::Bzip2::pod::FAQ - -Frequently Asked Questions about Compress::Raw::Bzip2 - -=item Compress::Raw::Zlib - -Low-Level Interface to zlib compression library - -=item Compress::Raw::Zlib::pod::FAQ - -Frequently Asked Questions about Compress::Raw::Zlib - -=item Compress::Zlib - -Interface to zlib compression library - -=item Config - -Access Perl configuration information - -=item Cwd - -Get pathname of current working directory - -=item DB - -Programmatic interface to the Perl debugging API - -=item DBM_Filter - -Filter DBM keys/values - -=item DBM_Filter::compress - -Filter for DBM_Filter - -=item DBM_Filter::encode - -Filter for DBM_Filter - -=item DBM_Filter::int32 - -Filter for DBM_Filter - -=item DBM_Filter::null - -Filter for DBM_Filter - -=item DBM_Filter::utf8 - -Filter for DBM_Filter - -=item DB_File - -Perl5 access to Berkeley DB version 1.x - -=item Data::Dumper - -Stringified perl data structures, suitable for both printing and C - -=item Devel::DProf - -A Perl code profiler - -=item Devel::InnerPackage - -Find all the inner packages of a package - -=item Devel::Peek - -A data debugging tool for the XS programmer - -=item Devel::SelfStubber - -Generate stubs for a SelfLoading module - -=item Digest - -Modules that calculate message digests - -=item Digest::MD5 - -Perl interface to the MD5 Algorithm - -=item Digest::SHA - -Perl extension for SHA-1/224/256/384/512 - -=item Digest::base - -Digest base class - -=item Digest::file - -Calculate digests of files - -=item DirHandle - -Supply object methods for directory handles - -=item Dumpvalue - -Provides screen dump of Perl data. - -=item DynaLoader - -Dynamically load C libraries into Perl code - -=item Encode - -Character encodings - -=item Encode::Alias - -Alias definitions to encodings - -=item Encode::Byte - -Single Byte Encodings - -=item Encode::CJKConstants - -Internally used by Encode::??::ISO_2022_* - -=item Encode::CN - -China-based Chinese Encodings - -=item Encode::CN::HZ - -Internally used by Encode::CN - -=item Encode::Config - -Internally used by Encode - -=item Encode::EBCDIC - -EBCDIC Encodings - -=item Encode::Encoder - -Object Oriented Encoder - -=item Encode::Encoding - -Encode Implementation Base Class - -=item Encode::GSM0338 - -ESTI GSM 03.38 Encoding - -=item Encode::Guess - -Guesses encoding from data - -=item Encode::JP - -Japanese Encodings - -=item Encode::JP::H2Z - -Internally used by Encode::JP::2022_JP* - -=item Encode::JP::JIS7 - -Internally used by Encode::JP - -=item Encode::KR - -Korean Encodings - -=item Encode::KR::2022_KR - -Internally used by Encode::KR - -=item Encode::MIME::Header - -MIME 'B' and 'Q' header encoding - -=item Encode::MIME::Name - -Internally used by Encode - -=item Encode::PerlIO - -A detailed document on Encode and PerlIO - -=item Encode::Supported - -Encodings supported by Encode - -=item Encode::Symbol - -Symbol Encodings - -=item Encode::TW - -Taiwan-based Chinese Encodings - -=item Encode::Unicode - -Various Unicode Transformation Formats - -=item Encode::Unicode::UTF7 - -UTF-7 encoding - -=item English - -Use nice English (or awk) names for ugly punctuation variables - -=item Env - -Perl module that imports environment variables as scalars or arrays - -=item Errno - -System errno constants - -=item Exporter - -Implements default import method for modules - -=item Exporter::Heavy - -Exporter guts - -=item ExtUtils::CBuilder - -Compile and link C code for Perl modules - -=item ExtUtils::CBuilder::Platform::Windows - -Builder class for Windows platforms - -=item ExtUtils::Command - -Utilities to replace common UNIX commands in Makefiles etc. - -=item ExtUtils::Command::MM - -Commands for the MM's to use in Makefiles - -=item ExtUtils::Constant - -Generate XS code to import C header constants - -=item ExtUtils::Constant::Base - -Base class for ExtUtils::Constant objects - -=item ExtUtils::Constant::Utils - -Helper functions for ExtUtils::Constant - -=item ExtUtils::Constant::XS - -Base class for ExtUtils::Constant objects - -=item ExtUtils::Embed - -Utilities for embedding Perl in C/C++ applications - -=item ExtUtils::Install - -Install files from here to there - -=item ExtUtils::Installed - -Inventory management of installed modules - -=item ExtUtils::Liblist - -Determine libraries to use and how to use them - -=item ExtUtils::MM - -OS adjusted ExtUtils::MakeMaker subclass - -=item ExtUtils::MM_AIX - -AIX specific subclass of ExtUtils::MM_Unix - -=item ExtUtils::MM_Any - -Platform-agnostic MM methods - -=item ExtUtils::MM_BeOS - -Methods to override UN*X behaviour in ExtUtils::MakeMaker - -=item ExtUtils::MM_Cygwin - -Methods to override UN*X behaviour in ExtUtils::MakeMaker - -=item ExtUtils::MM_DOS - -DOS specific subclass of ExtUtils::MM_Unix - -=item ExtUtils::MM_Darwin - -Special behaviors for OS X - -=item ExtUtils::MM_MacOS - -Once produced Makefiles for MacOS Classic - -=item ExtUtils::MM_NW5 - -Methods to override UN*X behaviour in ExtUtils::MakeMaker - -=item ExtUtils::MM_OS2 - -Methods to override UN*X behaviour in ExtUtils::MakeMaker - -=item ExtUtils::MM_QNX - -QNX specific subclass of ExtUtils::MM_Unix - -=item ExtUtils::MM_UWIN - -U/WIN specific subclass of ExtUtils::MM_Unix - -=item ExtUtils::MM_Unix - -Methods used by ExtUtils::MakeMaker - -=item ExtUtils::MM_VMS - -Methods to override UN*X behaviour in ExtUtils::MakeMaker - -=item ExtUtils::MM_VOS - -VOS specific subclass of ExtUtils::MM_Unix - -=item ExtUtils::MM_Win32 - -Methods to override UN*X behaviour in ExtUtils::MakeMaker - -=item ExtUtils::MM_Win95 - -Method to customize MakeMaker for Win9X - -=item ExtUtils::MY - -ExtUtils::MakeMaker subclass for customization - -=item ExtUtils::MakeMaker - -Create a module Makefile - -=item ExtUtils::MakeMaker::Config - -Wrapper around Config.pm - -=item ExtUtils::MakeMaker::FAQ - -Frequently Asked Questions About MakeMaker - -=item ExtUtils::MakeMaker::Tutorial - -Writing a module with MakeMaker - -=item ExtUtils::Manifest - -Utilities to write and check a MANIFEST file - -=item ExtUtils::Mkbootstrap - -Make a bootstrap file for use by DynaLoader - -=item ExtUtils::Mksymlists - -Write linker options files for dynamic extension - -=item ExtUtils::Packlist - -Manage .packlist files - -=item ExtUtils::ParseXS - -Converts Perl XS code into C code - -=item ExtUtils::XSSymSet - -Keep sets of symbol names palatable to the VMS linker - -=item ExtUtils::testlib - -Add blib/* directories to @INC - -=item Fatal - -Replace functions with equivalents which succeed or die - -=item Fcntl - -Load the C Fcntl.h defines - -=item File::Basename - -Parse file paths into directory, filename and suffix. - -=item File::CheckTree - -Run many filetest checks on a tree - -=item File::Compare - -Compare files or filehandles - -=item File::Copy - -Copy files or filehandles - -=item File::DosGlob - -DOS like globbing and then some - -=item File::Fetch - -A generic file fetching mechanism - -=item File::Find - -Traverse a directory tree. - -=item File::Glob - -Perl extension for BSD glob routine - -=item File::GlobMapper - -Extend File Glob to Allow Input and Output Files - -=item File::Path - -Create or remove directory trees - -=item File::Spec - -Portably perform operations on file names - -=item File::Spec::Cygwin - -Methods for Cygwin file specs - -=item File::Spec::Epoc - -Methods for Epoc file specs - -=item File::Spec::Functions - -Portably perform operations on file names - -=item File::Spec::Mac - -File::Spec for Mac OS (Classic) - -=item File::Spec::OS2 - -Methods for OS/2 file specs - -=item File::Spec::Unix - -File::Spec for Unix, base for other File::Spec modules - -=item File::Spec::VMS - -Methods for VMS file specs - -=item File::Spec::Win32 - -Methods for Win32 file specs - -=item File::Temp - -Return name and handle of a temporary file safely - -=item File::stat - -By-name interface to Perl's built-in stat() functions - -=item FileCache - -Keep more files open than the system permits - -=item FileHandle - -Supply object methods for filehandles - -=item Filter::Simple - -Simplified source filtering - -=item Filter::Util::Call - -Perl Source Filter Utility Module - -=item FindBin - -Locate directory of original perl script - -=item GDBM_File - -Perl5 access to the gdbm library. - -=item Getopt::Long - -Extended processing of command line options - -=item Getopt::Std - -Process single-character switches with switch clustering - -=item Hash::Util - -A selection of general-utility hash subroutines - -=item Hash::Util::FieldHash - -Support for Inside-Out Classes - -=item I18N::Collate - -Compare 8-bit scalar data according to the current locale - -=item I18N::LangTags - -Functions for dealing with RFC3066-style language tags - -=item I18N::LangTags::Detect - -Detect the user's language preferences - -=item I18N::LangTags::List - -Tags and names for human languages - -=item I18N::Langinfo - -Query locale information - -=item IO - -Load various IO modules - -=item IO::Compress::Base - -Base Class for IO::Compress modules - -=item IO::Compress::Bzip2 - -Write bzip2 files/buffers - -=item IO::Compress::Deflate - -Write RFC 1950 files/buffers - -=item IO::Compress::Gzip - -Write RFC 1952 files/buffers - -=item IO::Compress::RawDeflate - -Write RFC 1951 files/buffers - -=item IO::Compress::Zip - -Write zip files/buffers - -=item IO::Compress::pod::FAQ - -Frequently Asked Questions about IO::Compress - -=item IO::Dir - -Supply object methods for directory handles - -=item IO::File - -Supply object methods for filehandles - -=item IO::Handle - -Supply object methods for I/O handles - -=item IO::Pipe - -Supply object methods for pipes - -=item IO::Poll - -Object interface to system poll call - -=item IO::Seekable - -Supply seek based methods for I/O objects - -=item IO::Select - -OO interface to the select system call - -=item IO::Socket - -Object interface to socket communications - -=item IO::Socket::INET - -Object interface for AF_INET domain sockets - -=item IO::Socket::UNIX - -Object interface for AF_UNIX domain sockets - -=item IO::Uncompress::AnyInflate - -Uncompress zlib-based (zip, gzip) file/buffer - -=item IO::Uncompress::AnyUncompress - -Uncompress gzip, zip, bzip2 or lzop file/buffer - -=item IO::Uncompress::Base - -Base Class for IO::Uncompress modules - -=item IO::Uncompress::Bunzip2 - -Read bzip2 files/buffers - -=item IO::Uncompress::Gunzip - -Read RFC 1952 files/buffers - -=item IO::Uncompress::Inflate - -Read RFC 1950 files/buffers - -=item IO::Uncompress::RawInflate - -Read RFC 1951 files/buffers - -=item IO::Uncompress::Unzip - -Read zip files/buffers - -=item IO::Zlib - -IO:: style interface to L - -=item IPC::Cmd - -Finding and running system commands made easy - -=item IPC::Msg - -SysV Msg IPC object class - -=item IPC::Open2 - -Open a process for both reading and writing - -=item IPC::Open3 - -Open a process for reading, writing, and error handling - -=item IPC::Semaphore - -SysV Semaphore IPC object class - -=item IPC::SharedMem - -SysV Shared Memory IPC object class - -=item IPC::SysV - -System V IPC constants and system calls - -=item List::Util - -A selection of general-utility list subroutines - -=item Locale::Constants - -Constants for Locale codes - -=item Locale::Country - -ISO codes for country identification (ISO 3166) - -=item Locale::Currency - -ISO three letter codes for currency identification (ISO 4217) - -=item Locale::Language - -ISO two letter codes for language identification (ISO 639) - -=item Locale::Maketext - -Framework for localization - -=item Locale::Maketext::Simple - -Simple interface to Locale::Maketext::Lexicon - -=item Locale::Maketext::TPJ13 - -Article about software localization - -=item Locale::Script - -ISO codes for script identification (ISO 15924) - -=item Log::Message - -A generic message storing mechanism; - -=item Log::Message::Config - -Configuration options for Log::Message - -=item Log::Message::Handlers - -Message handlers for Log::Message - -=item Log::Message::Item - -Message objects for Log::Message - -=item MIME::Base64 - -Encoding and decoding of base64 strings - -=item MIME::QuotedPrint - -Encoding and decoding of quoted-printable strings - -=item Math::BigFloat - -Arbitrary size floating point math package - -=item Math::BigInt - -Arbitrary size integer/float math package - -=item Math::BigInt::Calc - -Pure Perl module to support Math::BigInt - -=item Math::BigInt::CalcEmu - -Emulate low-level math with BigInt code - -=item Math::BigInt::FastCalc - -Math::BigInt::Calc with some XS for more speed - -=item Math::BigRat - -Arbitrary big rational numbers - -=item Math::Complex - -Complex numbers and associated mathematical functions - -=item Math::Trig - -Trigonometric functions - -=item Memoize - -Make functions faster by trading space for time - -=item Memoize::AnyDBM_File - -Glue to provide EXISTS for AnyDBM_File for Storable use - -=item Memoize::Expire - -Plug-in module for automatic expiration of memoized values - -=item Memoize::ExpireFile - -Test for Memoize expiration semantics - -=item Memoize::ExpireTest - -Test for Memoize expiration semantics - -=item Memoize::NDBM_File - -Glue to provide EXISTS for NDBM_File for Storable use - -=item Memoize::SDBM_File - -Glue to provide EXISTS for SDBM_File for Storable use - -=item Memoize::Storable - -Store Memoized data in Storable database - -=item Module::Build - -Build and install Perl modules - -=item Module::Build::API - -API Reference for Module Authors - -=item Module::Build::Authoring - -Authoring Module::Build modules - -=item Module::Build::Base - -Default methods for Module::Build - -=item Module::Build::Compat - -Compatibility with ExtUtils::MakeMaker - -=item Module::Build::ConfigData - -Configuration for Module::Build - -=item Module::Build::Cookbook - -Examples of Module::Build Usage - -=item Module::Build::ModuleInfo - -Gather package and POD information from a perl module files - -=item Module::Build::Notes - -Configuration for $module_name - -=item Module::Build::PPMMaker - -Perl Package Manager file creation - -=item Module::Build::Platform::Amiga - -Builder class for Amiga platforms - -=item Module::Build::Platform::Default - -Stub class for unknown platforms - -=item Module::Build::Platform::EBCDIC - -Builder class for EBCDIC platforms - -=item Module::Build::Platform::MPEiX - -Builder class for MPEiX platforms - -=item Module::Build::Platform::MacOS - -Builder class for MacOS platforms - -=item Module::Build::Platform::RiscOS - -Builder class for RiscOS platforms - -=item Module::Build::Platform::Unix - -Builder class for Unix platforms - -=item Module::Build::Platform::VMS - -Builder class for VMS platforms - -=item Module::Build::Platform::VOS - -Builder class for VOS platforms - -=item Module::Build::Platform::Windows - -Builder class for Windows platforms - -=item Module::Build::Platform::aix - -Builder class for AIX platform - -=item Module::Build::Platform::cygwin - -Builder class for Cygwin platform - -=item Module::Build::Platform::darwin - -Builder class for Mac OS X platform - -=item Module::Build::Platform::os2 - -Builder class for OS/2 platform - -=item Module::Build::YAML - -Provides just enough YAML support so that Module::Build works even if YAML.pm is not installed - -=item Module::CoreList - -What modules shipped with versions of perl - -=item Module::Load - -Runtime require of both modules and files - -=item Module::Load::Conditional - -Looking up module information / loading at runtime - -=item Module::Loaded - -Mark modules as loaded or unloaded - -=item Module::Pluggable - -Automatically give your module the ability to have plugins - -=item Module::Pluggable::Object - -Automatically give your module the ability to have plugins - -=item NDBM_File - -Tied access to ndbm files - -=item NEXT - -Provide a pseudo-class NEXT (et al) that allows method redispatch - -=item Net::Cmd - -Network Command class (as used by FTP, SMTP etc) - -=item Net::Config - -Local configuration data for libnet - -=item Net::Domain - -Attempt to evaluate the current host's internet name and domain - -=item Net::FTP - -FTP Client class - -=item Net::NNTP - -NNTP Client class - -=item Net::Netrc - -OO interface to users netrc file - -=item Net::POP3 - -Post Office Protocol 3 Client class (RFC1939) - -=item Net::Ping - -Check a remote host for reachability - -=item Net::SMTP - -Simple Mail Transfer Protocol Client - -=item Net::Time - -Time and daytime network client interface - -=item Net::hostent - -By-name interface to Perl's built-in gethost*() functions - -=item Net::libnetFAQ - -Libnet Frequently Asked Questions - -=item Net::netent - -By-name interface to Perl's built-in getnet*() functions - -=item Net::protoent - -By-name interface to Perl's built-in getproto*() functions - -=item Net::servent - -By-name interface to Perl's built-in getserv*() functions - -=item O - -Generic interface to Perl Compiler backends - -=item ODBM_File - -Tied access to odbm files - -=item Opcode - -Disable named opcodes when compiling perl code - -=item POSIX - -Perl interface to IEEE Std 1003.1 - -=item Package::Constants - -List all constants declared in a package - -=item Params::Check - -A generic input parsing/checking mechanism. - -=item Parse::CPAN::Meta - -Parse META.yml and other similar CPAN metadata files - -=item PerlIO - -On demand loader for PerlIO layers and root of PerlIO::* name space - -=item PerlIO::encoding - -Encoding layer - -=item PerlIO::scalar - -In-memory IO, scalar IO - -=item PerlIO::via - -Helper class for PerlIO layers implemented in perl - -=item PerlIO::via::QuotedPrint - -PerlIO layer for quoted-printable strings - -=item Pod::Checker - -Check pod documents for syntax errors - -=item Pod::Escapes - -For resolving Pod EE...E sequences - -=item Pod::Find - -Find POD documents in directory trees - -=item Pod::Functions - -Group Perl's functions a la perlfunc.pod - -=item Pod::Html - -Module to convert pod files to HTML - -=item Pod::InputObjects - -Objects representing POD input paragraphs, commands, etc. - -=item Pod::LaTeX - -Convert Pod data to formatted Latex - -=item Pod::Man - -Convert POD data to formatted *roff input - -=item Pod::ParseLink - -Parse an LEE formatting code in POD text - -=item Pod::ParseUtils - -Helpers for POD parsing and conversion - -=item Pod::Parser - -Base class for creating POD filters and translators - -=item Pod::Perldoc - -Look up Perl documentation in Pod format. - -=item Pod::Perldoc::BaseTo - -Base for Pod::Perldoc formatters - -=item Pod::Perldoc::GetOptsOO - -Customized option parser for Pod::Perldoc - -=item Pod::Perldoc::ToChecker - -Let Perldoc check Pod for errors - -=item Pod::Perldoc::ToMan - -Let Perldoc render Pod as man pages - -=item Pod::Perldoc::ToNroff - -Let Perldoc convert Pod to nroff - -=item Pod::Perldoc::ToPod - -Let Perldoc render Pod as ... Pod! - -=item Pod::Perldoc::ToRtf - -Let Perldoc render Pod as RTF - -=item Pod::Perldoc::ToText - -Let Perldoc render Pod as plaintext - -=item Pod::Perldoc::ToTk - -Let Perldoc use Tk::Pod to render Pod - -=item Pod::Perldoc::ToXml - -Let Perldoc render Pod as XML - -=item Pod::PlainText - -Convert POD data to formatted ASCII text - -=item Pod::Plainer - -Perl extension for converting Pod to old style Pod. - -=item Pod::Select - -Extract selected sections of POD from input - -=item Pod::Simple - -Framework for parsing Pod - -=item Pod::Simple::Checker - -Check the Pod syntax of a document - -=item Pod::Simple::Debug - -Put Pod::Simple into trace/debug mode - -=item Pod::Simple::DumpAsText - -Dump Pod-parsing events as text - -=item Pod::Simple::DumpAsXML - -Turn Pod into XML - -=item Pod::Simple::HTML - -Convert Pod to HTML - -=item Pod::Simple::HTMLBatch - -Convert several Pod files to several HTML files - -=item Pod::Simple::LinkSection - -Represent "section" attributes of L codes - -=item Pod::Simple::Methody - -Turn Pod::Simple events into method calls - -=item Pod::Simple::PullParser - -A pull-parser interface to parsing Pod - -=item Pod::Simple::PullParserEndToken - -End-tokens from Pod::Simple::PullParser - -=item Pod::Simple::PullParserStartToken - -Start-tokens from Pod::Simple::PullParser - -=item Pod::Simple::PullParserTextToken - -Text-tokens from Pod::Simple::PullParser - -=item Pod::Simple::PullParserToken - -Tokens from Pod::Simple::PullParser - -=item Pod::Simple::RTF - -Format Pod as RTF - -=item Pod::Simple::Search - -Find POD documents in directory trees - -=item Pod::Simple::SimpleTree - -Parse Pod into a simple parse tree - -=item Pod::Simple::Subclassing - -Write a formatter as a Pod::Simple subclass - -=item Pod::Simple::Text - -Format Pod as plaintext - -=item Pod::Simple::TextContent - -Get the text content of Pod - -=item Pod::Simple::XHTML - -Format Pod as validating XHTML - -=item Pod::Simple::XMLOutStream - -Turn Pod into XML - -=item Pod::Text - -Convert POD data to formatted ASCII text - -=item Pod::Text::Color - -Convert POD data to formatted color ASCII text - -=item Pod::Text::Termcap - -Convert POD data to ASCII text with format escapes - -=item Pod::Usage - -Print a usage message from embedded pod documentation - -=item SDBM_File - -Tied access to sdbm files - -=item Safe - -Compile and execute code in restricted compartments - -=item Scalar::Util - -A selection of general-utility scalar subroutines - -=item Search::Dict - -Search for key in dictionary file - -=item SelectSaver - -Save and restore selected file handle - -=item SelfLoader - -Load functions only on demand - -=item Shell - -Run shell commands transparently within perl - -=item Socket - -Load the C socket.h defines and structure manipulators - -=item Storable - -Persistence for Perl data structures - -=item Switch - -A switch statement for Perl - -=item Symbol - -Manipulate Perl symbols and their names - -=item Sys::Hostname - -Try every conceivable way to get hostname - -=item Sys::Syslog - -Perl interface to the UNIX syslog(3) calls - -=item Sys::Syslog::win32::Win32 - -Win32 support for Sys::Syslog - -=item TAP::Base - -Base class that provides common functionality to L - -=item TAP::Formatter::Base - -Harness output delegate for default console output - -=item TAP::Formatter::Color - -Run Perl test scripts with color - -=item TAP::Formatter::Console - -Harness output delegate for default console output - -=item TAP::Formatter::Console::ParallelSession - -Harness output delegate for parallel console output - -=item TAP::Formatter::Console::Session - -Harness output delegate for default console output - -=item TAP::Formatter::File - -Harness output delegate for file output - -=item TAP::Formatter::File::Session - -Harness output delegate for file output - -=item TAP::Formatter::Session - -Abstract base class for harness output delegate - -=item TAP::Harness - -Run test scripts with statistics - -=item TAP::Object - -Base class that provides common functionality to all C modules - -=item TAP::Parser - -Parse L output - -=item TAP::Parser::Aggregator - -Aggregate TAP::Parser results - -=item TAP::Parser::Grammar - -A grammar for the Test Anything Protocol. - -=item TAP::Parser::Iterator - -Internal base class for TAP::Parser Iterators - -=item TAP::Parser::Iterator::Array - -Internal TAP::Parser array Iterator - -=item TAP::Parser::Iterator::Process - -Internal TAP::Parser Iterator - -=item TAP::Parser::Iterator::Stream - -Internal TAP::Parser Iterator - -=item TAP::Parser::IteratorFactory - -Internal TAP::Parser Iterator - -=item TAP::Parser::Multiplexer - -Multiplex multiple TAP::Parsers - -=item TAP::Parser::Result - -Base class for TAP::Parser output objects - -=item TAP::Parser::Result::Bailout - -Bailout result token. - -=item TAP::Parser::Result::Comment - -Comment result token. - -=item TAP::Parser::Result::Plan - -Plan result token. - -=item TAP::Parser::Result::Pragma - -TAP pragma token. - -=item TAP::Parser::Result::Test - -Test result token. - -=item TAP::Parser::Result::Unknown - -Unknown result token. - -=item TAP::Parser::Result::Version - -TAP syntax version token. - -=item TAP::Parser::Result::YAML - -YAML result token. - -=item TAP::Parser::ResultFactory - -Factory for creating TAP::Parser output objects - -=item TAP::Parser::Scheduler - -Schedule tests during parallel testing - -=item TAP::Parser::Scheduler::Job - -A single testing job. - -=item TAP::Parser::Scheduler::Spinner - -A no-op job. - -=item TAP::Parser::Source - -Stream output from some source - -=item TAP::Parser::Source::Perl - -Stream Perl output - -=item TAP::Parser::Utils - -Internal TAP::Parser utilities - -=item TAP::Parser::YAMLish::Reader - -Read YAMLish data from iterator - -=item TAP::Parser::YAMLish::Writer - -Write YAMLish data - -=item Term::ANSIColor - -Color screen output using ANSI escape sequences - -=item Term::Cap - -Perl termcap interface - -=item Term::Complete - -Perl word completion module - -=item Term::ReadLine - -Perl interface to various C packages. - -=item Term::UI - -Term::ReadLine UI made easy - -=item Test - -Provides a simple framework for writing test scripts - -=item Test::Builder - -Backend for building test libraries - -=item Test::Builder::Module - -Base class for test modules - -=item Test::Builder::Tester - -Test testsuites that have been built with - -=item Test::Builder::Tester::Color - -Turn on colour in Test::Builder::Tester - -=item Test::Harness - -Run Perl standard test scripts with statistics - -=item Test::More - -Yet another framework for writing test scripts - -=item Test::Simple - -Basic utilities for writing tests. - -=item Text::Abbrev - -Create an abbreviation table from a list - -=item Text::Balanced - -Extract delimited text sequences from strings. - -=item Text::ParseWords - -Parse text into an array of tokens or array of arrays - -=item Text::Soundex - -Implementation of the soundex algorithm. - -=item Text::Tabs - -Expand and unexpand tabs per the unix expand(1) and unexpand(1) - -=item Text::Wrap - -Line wrapping to form simple paragraphs - -=item Thread - -Manipulate threads in Perl (for old code only) - -=item Thread::Queue - -Thread-safe queues - -=item Thread::Semaphore - -Thread-safe semaphores - -=item Tie::Array - -Base class for tied arrays - -=item Tie::File - -Access the lines of a disk file via a Perl array - -=item Tie::Handle - -Base class definitions for tied handles - -=item Tie::Hash - -Base class definitions for tied hashes - -=item Tie::Hash::NamedCapture - -Named regexp capture buffers - -=item Tie::Memoize - -Add data to hash when needed - -=item Tie::RefHash - -Use references as hash keys - -=item Tie::Scalar - -Base class definitions for tied scalars - -=item Tie::StdHandle - -Base class definitions for tied handles - -=item Tie::SubstrHash - -Fixed-table-size, fixed-key-length hashing - -=item Time::HiRes - -High resolution alarm, sleep, gettimeofday, interval timers - -=item Time::Local - -Efficiently compute time from local and GMT time - -=item Time::Piece - -Object Oriented time objects - -=item Time::Piece::Seconds - -A simple API to convert seconds to other date values - -=item Time::gmtime - -By-name interface to Perl's built-in gmtime() function - -=item Time::localtime - -By-name interface to Perl's built-in localtime() function - -=item Time::tm - -Internal object used by Time::gmtime and Time::localtime - -=item UNIVERSAL - -Base class for ALL classes (blessed references) - -=item Unicode::Collate - -Unicode Collation Algorithm - -=item Unicode::Normalize - -Unicode Normalization Forms - -=item Unicode::UCD - -Unicode character database - -=item User::grent - -By-name interface to Perl's built-in getgr*() functions - -=item User::pwent - -By-name interface to Perl's built-in getpw*() functions - -=item Win32 - -Interfaces to some Win32 API Functions - -=item Win32API::File - -Low-level access to Win32 system API calls for files/dirs. - -=item Win32CORE - -Win32 CORE function stubs - -=item XS::APItest - -Test the perl C API - -=item XS::Typemap - -Module to test the XS typemaps distributed with perl - -=item XSLoader - -Dynamically load C libraries into Perl code - -=back - -To find out I modules installed on your system, including -those without documentation or outside the standard release, -just use the following command (under the default win32 shell, -double quotes should be used instead of single quotes). - - % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \ - 'find { wanted => sub { print canonpath $_ if /\.pm\z/ }, - no_chdir => 1 }, @INC' - -(The -T is here to prevent '.' from being listed in @INC.) -They should all have their own documentation installed and accessible -via your system man(1) command. If you do not have a B -program, you can use the Perl B program instead, which -generates Perl code as output you can run through perl. If you -have a B program but it doesn't find your modules, you'll have -to fix your manpath. See L for details. If you have no -system B command, you might try the B program. - -Note also that the command C gives you a (possibly -incomplete) list of the modules that have been further installed on -your system. (The perllocal.pod file is updated by the standard MakeMaker -install process.) - -=head2 Extension Modules - -Extension modules are written in C (or a mix of Perl and C). They -are usually dynamically loaded into Perl if and when you need them, -but may also be linked in statically. Supported extension modules -include Socket, Fcntl, and POSIX. - -Many popular C extension modules do not come bundled (at least, not -completely) due to their sizes, volatility, or simply lack of time -for adequate testing and configuration across the multitude of -platforms on which Perl was beta-tested. You are encouraged to -look for them on CPAN (described below), or using web search engines -like Alta Vista or Google. - -=head1 CPAN - -CPAN stands for Comprehensive Perl Archive Network; it's a globally -replicated trove of Perl materials, including documentation, style -guides, tricks and traps, alternate ports to non-Unix systems and -occasional binary distributions for these. Search engines for -CPAN can be found at http://www.cpan.org/ - -Most importantly, CPAN includes around a thousand unbundled modules, -some of which require a C compiler to build. Major categories of -modules are: - -=over - -=item * - -Language Extensions and Documentation Tools - -=item * - -Development Support - -=item * - -Operating System Interfaces - -=item * - -Networking, Device Control (modems) and InterProcess Communication - -=item * - -Data Types and Data Type Utilities - -=item * - -Database Interfaces - -=item * - -User Interfaces - -=item * - -Interfaces to / Emulations of Other Programming Languages - -=item * - -File Names, File Systems and File Locking (see also File Handles) - -=item * - -String Processing, Language Text Processing, Parsing, and Searching - -=item * - -Option, Argument, Parameter, and Configuration File Processing - -=item * - -Internationalization and Locale - -=item * - -Authentication, Security, and Encryption - -=item * - -World Wide Web, HTML, HTTP, CGI, MIME - -=item * - -Server and Daemon Utilities - -=item * - -Archiving and Compression - -=item * - -Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing - -=item * - -Mail and Usenet News - -=item * - -Control Flow Utilities (callbacks and exceptions etc) - -=item * - -File Handle and Input/Output Stream Utilities - -=item * - -Miscellaneous Modules - -=back - -The list of the registered CPAN sites as of this writing follows. -Please note that the sorting order is alphabetical on fields: - -Continent - | - |-->Country - | - |-->[state/province] - | - |-->ftp - | - |-->[http] - -and thus the North American servers happen to be listed between the -European and the South American sites. - -You should try to choose one close to you. - -=head2 Africa - -=over 4 - -=item South Africa - - http://ftp.rucus.ru.ac.za/pub/perl/CPAN/ - ftp://ftp.rucus.ru.ac.za/pub/perl/CPAN/ - ftp://ftp.is.co.za/programming/perl/CPAN/ - ftp://ftp.saix.net/pub/CPAN/ - ftp://ftp.sun.ac.za/CPAN/CPAN/ - -=back - -=head2 Asia - -=over 4 - -=item China - - http://cpan.linuxforum.net/ - http://cpan.shellhung.org/ - ftp://ftp.shellhung.org/pub/CPAN - ftp://mirrors.hknet.com/CPAN - -=item Indonesia - - http://mirrors.tf.itb.ac.id/cpan/ - http://cpan.cbn.net.id/ - ftp://ftp.cbn.net.id/mirror/CPAN - -=item Israel - - ftp://ftp.iglu.org.il/pub/CPAN/ - http://cpan.lerner.co.il/ - http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/ - ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/ - -=item Japan - - ftp://ftp.u-aizu.ac.jp/pub/CPAN - ftp://ftp.kddlabs.co.jp/CPAN/ - ftp://ftp.ayamura.org/pub/CPAN/ - ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/ - http://ftp.cpan.jp/ - ftp://ftp.cpan.jp/CPAN/ - ftp://ftp.dti.ad.jp/pub/lang/CPAN/ - ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/ - -=item Malaysia - - http://cpan.MyBSD.org.my - http://mirror.leafbug.org/pub/CPAN - http://ossig.mncc.com.my/mirror/pub/CPAN - -=item Russian Federation - - http://cpan.tomsk.ru - ftp://cpan.tomsk.ru/ - -=item Saudi Arabia - - ftp://ftp.isu.net.sa/pub/CPAN/ - -=item Singapore - - http://CPAN.en.com.sg/ - ftp://cpan.en.com.sg/ - http://mirror.averse.net/pub/CPAN - ftp://mirror.averse.net/pub/CPAN - http://cpan.oss.eznetsols.org - ftp://ftp.oss.eznetsols.org/cpan - -=item South Korea - - http://CPAN.bora.net/ - ftp://ftp.bora.net/pub/CPAN/ - http://mirror.kr.FreeBSD.org/CPAN - ftp://ftp.kr.FreeBSD.org/pub/CPAN - -=item Taiwan - - ftp://ftp.nctu.edu.tw/UNIX/perl/CPAN - http://cpan.cdpa.nsysu.edu.tw/ - ftp://cpan.cdpa.nsysu.edu.tw/pub/CPAN - http://ftp.isu.edu.tw/pub/CPAN - ftp://ftp.isu.edu.tw/pub/CPAN - ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/ - http://ftp.tku.edu.tw/pub/CPAN/ - ftp://ftp.tku.edu.tw/pub/CPAN/ - -=item Thailand - - ftp://ftp.loxinfo.co.th/pub/cpan/ - ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/ - -=back - -=head2 Central America - -=over 4 - -=item Costa Rica - - http://ftp.ucr.ac.cr/Unix/CPAN/ - ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/ - -=back - -=head2 Europe - -=over 4 - -=item Austria - - http://cpan.inode.at/ - ftp://cpan.inode.at - ftp://ftp.tuwien.ac.at/pub/CPAN/ - -=item Belgium - - http://ftp.easynet.be/pub/CPAN/ - ftp://ftp.easynet.be/pub/CPAN/ - http://cpan.skynet.be - ftp://ftp.cpan.skynet.be/pub/CPAN - ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/ - -=item Bosnia and Herzegovina - - http://cpan.blic.net/ - -=item Bulgaria - - http://cpan.online.bg - ftp://cpan.online.bg/cpan - http://cpan.zadnik.org - ftp://ftp.zadnik.org/mirrors/CPAN/ - http://cpan.lirex.net/ - ftp://ftp.lirex.net/pub/mirrors/CPAN - -=item Croatia - - http://ftp.linux.hr/pub/CPAN/ - ftp://ftp.linux.hr/pub/CPAN/ - -=item Czech Republic - - ftp://ftp.fi.muni.cz/pub/CPAN/ - ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/ - -=item Denmark - - http://mirrors.sunsite.dk/cpan/ - ftp://sunsite.dk/mirrors/cpan/ - http://cpan.cybercity.dk - http://www.cpan.dk/CPAN/ - ftp://www.cpan.dk/ftp.cpan.org/CPAN/ - -=item Estonia - - ftp://ftp.ut.ee/pub/languages/perl/CPAN/ - -=item Finland - - ftp://ftp.funet.fi/pub/languages/perl/CPAN/ - http://mirror.eunet.fi/CPAN - -=item France - - http://www.enstimac.fr/Perl/CPAN - http://ftp.u-paris10.fr/perl/CPAN - ftp://ftp.u-paris10.fr/perl/CPAN - http://cpan.mirrors.easynet.fr/ - ftp://cpan.mirrors.easynet.fr/pub/ftp.cpan.org/ - ftp://ftp.club-internet.fr/pub/perl/CPAN/ - http://fr.cpan.org/ - ftp://ftp.lip6.fr/pub/perl/CPAN/ - ftp://ftp.oleane.net/pub/mirrors/CPAN/ - ftp://ftp.pasteur.fr/pub/computing/CPAN/ - http://mir2.ovh.net/ftp.cpan.org - ftp://mir1.ovh.net/ftp.cpan.org - http://ftp.crihan.fr/mirrors/ftp.cpan.org/ - ftp://ftp.crihan.fr/mirrors/ftp.cpan.org/ - http://ftp.u-strasbg.fr/CPAN - ftp://ftp.u-strasbg.fr/CPAN - ftp://cpan.cict.fr/pub/CPAN/ - ftp://ftp.uvsq.fr/pub/perl/CPAN/ - -=item Germany - - ftp://ftp.rub.de/pub/CPAN/ - ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/ - ftp://ftp.uni-erlangen.de/pub/source/CPAN/ - ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN - http://pandemonium.tiscali.de/pub/CPAN/ - ftp://pandemonium.tiscali.de/pub/CPAN/ - http://ftp.gwdg.de/pub/languages/perl/CPAN/ - ftp://ftp.gwdg.de/pub/languages/perl/CPAN/ - ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/ - ftp://ftp.leo.org/pub/CPAN/ - http://cpan.noris.de/ - ftp://cpan.noris.de/pub/CPAN/ - ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/ - ftp://ftp.gmd.de/mirrors/CPAN/ - -=item Greece - - ftp://ftp.acn.gr/pub/lang/perl - ftp://ftp.forthnet.gr/pub/languages/perl/CPAN - ftp://ftp.ntua.gr/pub/lang/perl/ - -=item Hungary - - http://ftp.kfki.hu/packages/perl/CPAN/ - ftp://ftp.kfki.hu/pub/packages/perl/CPAN/ - -=item Iceland - - http://ftp.rhnet.is/pub/CPAN/ - ftp://ftp.rhnet.is/pub/CPAN/ - -=item Ireland - - http://cpan.indigo.ie/ - ftp://cpan.indigo.ie/pub/CPAN/ - http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN - ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN - http://sunsite.compapp.dcu.ie/pub/perl/ - ftp://sunsite.compapp.dcu.ie/pub/perl/ - -=item Italy - - http://cpan.nettuno.it/ - http://gusp.dyndns.org/CPAN/ - ftp://gusp.dyndns.org/pub/CPAN - http://softcity.iol.it/cpan - ftp://softcity.iol.it/pub/cpan - ftp://ftp.unina.it/pub/Other/CPAN/CPAN/ - ftp://ftp.unipi.it/pub/mirror/perl/CPAN/ - ftp://cis.uniRoma2.it/CPAN/ - ftp://ftp.edisontel.it/pub/CPAN_Mirror/ - http://cpan.flashnet.it/ - ftp://ftp.flashnet.it/pub/CPAN/ - -=item Latvia - - http://kvin.lv/pub/CPAN/ - -=item Lithuania - - ftp://ftp.unix.lt/pub/CPAN/ - -=item Netherlands - - ftp://download.xs4all.nl/pub/mirror/CPAN/ - ftp://ftp.nl.uu.net/pub/CPAN/ - ftp://ftp.nluug.nl/pub/languages/perl/CPAN/ - http://cpan.cybercomm.nl/ - ftp://mirror.cybercomm.nl/pub/CPAN - ftp://mirror.vuurwerk.nl/pub/CPAN/ - ftp://ftp.cpan.nl/pub/CPAN/ - http://ftp.easynet.nl/mirror/CPAN - ftp://ftp.easynet.nl/mirror/CPAN - http://archive.cs.uu.nl/mirror/CPAN/ - ftp://ftp.cs.uu.nl/mirror/CPAN/ - -=item Norway - - ftp://ftp.uninett.no/pub/languages/perl/CPAN - ftp://ftp.uit.no/pub/languages/perl/cpan/ - -=item Poland - - ftp://ftp.mega.net.pl/CPAN - ftp://ftp.man.torun.pl/pub/doc/CPAN/ - ftp://sunsite.icm.edu.pl/pub/CPAN/ - -=item Portugal - - ftp://ftp.ua.pt/pub/CPAN/ - ftp://perl.di.uminho.pt/pub/CPAN/ - http://cpan.dei.uc.pt/ - ftp://ftp.dei.uc.pt/pub/CPAN - ftp://ftp.nfsi.pt/pub/CPAN - http://ftp.linux.pt/pub/mirrors/CPAN - ftp://ftp.linux.pt/pub/mirrors/CPAN - http://cpan.ip.pt/ - ftp://cpan.ip.pt/pub/cpan/ - http://cpan.telepac.pt/ - ftp://ftp.telepac.pt/pub/cpan/ - -=item Romania - - ftp://ftp.bio-net.ro/pub/CPAN - ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/ - ftp://ftp.lug.ro/CPAN - ftp://ftp.roedu.net/pub/CPAN/ - ftp://ftp.dntis.ro/pub/cpan/ - ftp://ftp.iasi.roedu.net/pub/mirrors/ftp.cpan.org/ - http://cpan.ambra.ro/ - ftp://ftp.ambra.ro/pub/CPAN - ftp://ftp.dnttm.ro/pub/CPAN/ - ftp://ftp.lasting.ro/pub/CPAN - ftp://ftp.timisoara.roedu.net/mirrors/CPAN/ - -=item Russia - - ftp://ftp.chg.ru/pub/lang/perl/CPAN/ - http://cpan.rinet.ru/ - ftp://cpan.rinet.ru/pub/mirror/CPAN/ - ftp://ftp.aha.ru/pub/CPAN/ - ftp://ftp.corbina.ru/pub/CPAN/ - http://cpan.sai.msu.ru/ - ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/ - -=item Slovakia - - ftp://ftp.cvt.stuba.sk/pub/CPAN/ - -=item Slovenia - - ftp://ftp.arnes.si/software/perl/CPAN/ - -=item Spain - - http://cpan.imasd.elmundo.es/ - ftp://ftp.rediris.es/mirror/CPAN/ - ftp://ftp.ri.telefonica-data.net/CPAN - ftp://ftp.etse.urv.es/pub/perl/ - -=item Sweden - - http://ftp.du.se/CPAN/ - ftp://ftp.du.se/pub/CPAN/ - http://mirror.dataphone.se/CPAN - ftp://mirror.dataphone.se/pub/CPAN - ftp://ftp.sunet.se/pub/lang/perl/CPAN/ - -=item Switzerland - - http://cpan.mirror.solnet.ch/ - ftp://ftp.solnet.ch/mirror/CPAN/ - ftp://ftp.danyk.ch/CPAN/ - ftp://sunsite.cnlab-switch.ch/mirror/CPAN/ - -=item Turkey - - http://ftp.ulak.net.tr/perl/CPAN/ - ftp://ftp.ulak.net.tr/perl/CPAN - ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/ - -=item Ukraine - - http://cpan.org.ua/ - ftp://cpan.org.ua/ - ftp://ftp.perl.org.ua/pub/CPAN/ - http://no-more.kiev.ua/CPAN/ - ftp://no-more.kiev.ua/pub/CPAN/ - -=item United Kingdom - - http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN - ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/ - http://cpan.teleglobe.net/ - ftp://cpan.teleglobe.net/pub/CPAN - http://cpan.mirror.anlx.net/ - ftp://ftp.mirror.anlx.net/CPAN/ - http://cpan.etla.org/ - ftp://cpan.etla.org/pub/CPAN - ftp://ftp.demon.co.uk/pub/CPAN/ - http://cpan.m.flirble.org/ - ftp://ftp.flirble.org/pub/languages/perl/CPAN/ - ftp://ftp.plig.org/pub/CPAN/ - http://cpan.hambule.co.uk/ - http://cpan.mirrors.clockerz.net/ - ftp://ftp.clockerz.net/pub/CPAN/ - ftp://usit.shef.ac.uk/pub/packages/CPAN/ - -=back - -=head2 North America - -=over 4 - -=item Canada - -=over 8 - -=item Alberta - - http://cpan.sunsite.ualberta.ca/ - ftp://cpan.sunsite.ualberta.ca/pub/CPAN/ - -=item Manitoba - - http://theoryx5.uwinnipeg.ca/pub/CPAN/ - ftp://theoryx5.uwinnipeg.ca/pub/CPAN/ - -=item Nova Scotia - - ftp://cpan.chebucto.ns.ca/pub/CPAN/ - -=item Ontario - - ftp://ftp.nrc.ca/pub/CPAN/ - -=back - -=item Mexico - - http://cpan.azc.uam.mx - ftp://cpan.azc.uam.mx/mirrors/CPAN - http://www.cpan.unam.mx/ - ftp://ftp.unam.mx/pub/CPAN - http://www.msg.com.mx/CPAN/ - ftp://ftp.msg.com.mx/pub/CPAN/ - -=item United States - -=over 8 - -=item Alabama - - http://mirror.hiwaay.net/CPAN/ - ftp://mirror.hiwaay.net/CPAN/ - -=item California - - http://cpan.develooper.com/ - http://www.cpan.org/ - ftp://cpan.valueclick.com/pub/CPAN/ - http://www.mednor.net/ftp/pub/mirrors/CPAN/ - ftp://ftp.mednor.net/pub/mirrors/CPAN/ - http://mirrors.gossamer-threads.com/CPAN - ftp://cpan.nas.nasa.gov/pub/perl/CPAN/ - http://mirrors.kernel.org/cpan/ - ftp://mirrors.kernel.org/pub/CPAN - http://cpan-sj.viaverio.com/ - ftp://cpan-sj.viaverio.com/pub/CPAN/ - http://cpan.digisle.net/ - ftp://cpan.digisle.net/pub/CPAN - http://www.perl.com/CPAN/ - http://www.uberlan.net/CPAN - -=item Colorado - - ftp://ftp.cs.colorado.edu/pub/perl/CPAN/ - http://cpan.four10.com - -=item Delaware - - http://ftp.lug.udel.edu/pub/CPAN - ftp://ftp.lug.udel.edu/pub/CPAN - -=item District of Columbia - - ftp://ftp.dc.aleron.net/pub/CPAN/ - -=item Florida - - ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/ - http://mirror.csit.fsu.edu/pub/CPAN/ - ftp://mirror.csit.fsu.edu/pub/CPAN/ - http://cpan.mirrors.nks.net/ - -=item Indiana - - ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/ - http://cpan.netnitco.net/ - ftp://cpan.netnitco.net/pub/mirrors/CPAN/ - http://archive.progeny.com/CPAN/ - ftp://archive.progeny.com/CPAN/ - http://fx.saintjoe.edu/pub/CPAN - ftp://ftp.saintjoe.edu/pub/CPAN - http://csociety-ftp.ecn.purdue.edu/pub/CPAN - ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN - -=item Kentucky - - http://cpan.uky.edu/ - ftp://cpan.uky.edu/pub/CPAN/ - http://slugsite.louisville.edu/cpan - ftp://slugsite.louisville.edu/CPAN - -=item Massachusetts - - http://mirrors.towardex.com/CPAN - ftp://mirrors.towardex.com/pub/CPAN - ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/ - -=item Michigan - - ftp://cpan.cse.msu.edu/ - http://cpan.calvin.edu/pub/CPAN - ftp://cpan.calvin.edu/pub/CPAN - -=item Nevada - - http://www.oss.redundant.com/pub/CPAN - ftp://www.oss.redundant.com/pub/CPAN - -=item New Jersey - - http://ftp.cpanel.net/pub/CPAN/ - ftp://ftp.cpanel.net/pub/CPAN/ - http://cpan.teleglobe.net/ - ftp://cpan.teleglobe.net/pub/CPAN - -=item New York - - http://cpan.belfry.net/ - http://cpan.erlbaum.net/ - ftp://cpan.erlbaum.net/ - http://cpan.thepirtgroup.com/ - ftp://cpan.thepirtgroup.com/ - ftp://ftp.stealth.net/pub/CPAN/ - http://www.rge.com/pub/languages/perl/ - ftp://ftp.rge.com/pub/languages/perl/ - -=item North Carolina - - http://www.ibiblio.org/pub/languages/perl/CPAN - ftp://ftp.ibiblio.org/pub/languages/perl/CPAN - ftp://ftp.duke.edu/pub/perl/ - ftp://ftp.ncsu.edu/pub/mirror/CPAN/ - -=item Oklahoma - - ftp://ftp.ou.edu/mirrors/CPAN/ - -=item Oregon - - ftp://ftp.orst.edu/pub/CPAN - -=item Pennsylvania - - http://ftp.epix.net/CPAN/ - ftp://ftp.epix.net/pub/languages/perl/ - http://mirrors.phenominet.com/pub/CPAN/ - ftp://mirrors.phenominet.com/pub/CPAN/ - http://cpan.pair.com/ - ftp://cpan.pair.com/pub/CPAN/ - ftp://carroll.cac.psu.edu/pub/CPAN/ - -=item Tennessee - - ftp://ftp.sunsite.utk.edu/pub/CPAN/ - -=item Texas - - http://ftp.sedl.org/pub/mirrors/CPAN/ - http://www.binarycode.org/cpan - ftp://mirror.telentente.com/pub/CPAN - http://mirrors.theonlinerecordstore.com/CPAN - -=item Utah - - ftp://mirror.xmission.com/CPAN/ - -=item Virginia - - http://cpan-du.viaverio.com/ - ftp://cpan-du.viaverio.com/pub/CPAN/ - http://mirrors.rcn.net/pub/lang/CPAN/ - ftp://mirrors.rcn.net/pub/lang/CPAN/ - http://perl.secsup.org/ - ftp://perl.secsup.org/pub/perl/ - http://noc.cvaix.com/mirrors/CPAN/ - -=item Washington - - http://cpan.llarian.net/ - ftp://cpan.llarian.net/pub/CPAN/ - http://cpan.mirrorcentral.com/ - ftp://ftp.mirrorcentral.com/pub/CPAN/ - ftp://ftp-mirror.internap.com/pub/CPAN/ - -=item Wisconsin - - http://mirror.sit.wisc.edu/pub/CPAN/ - ftp://mirror.sit.wisc.edu/pub/CPAN/ - http://mirror.aphix.com/CPAN - ftp://mirror.aphix.com/pub/CPAN - -=back - -=back - -=head2 Oceania - -=over 4 - -=item Australia - - http://ftp.planetmirror.com/pub/CPAN/ - ftp://ftp.planetmirror.com/pub/CPAN/ - ftp://mirror.aarnet.edu.au/pub/perl/CPAN/ - ftp://cpan.topend.com.au/pub/CPAN/ - http://cpan.mirrors.ilisys.com.au - -=item New Zealand - - ftp://ftp.auckland.ac.nz/pub/perl/CPAN/ - -=item United States - - http://aniani.ifa.hawaii.edu/CPAN/ - ftp://aniani.ifa.hawaii.edu/CPAN/ - -=back - -=head2 South America - -=over 4 - -=item Argentina - - ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/ - http://www.linux.org.ar/mirrors/cpan - ftp://ftp.linux.org.ar/mirrors/cpan - -=item Brazil - - ftp://cpan.pop-mg.com.br/pub/CPAN/ - ftp://ftp.matrix.com.br/pub/perl/CPAN/ - http://cpan.hostsul.com.br/ - ftp://cpan.hostsul.com.br/ - -=item Chile - - http://cpan.netglobalis.net/ - ftp://cpan.netglobalis.net/pub/CPAN/ - -=back - -=head2 RSYNC Mirrors - - www.linux.org.ar::cpan - theoryx5.uwinnipeg.ca::CPAN - ftp.shellhung.org::CPAN - rsync.nic.funet.fi::CPAN - ftp.u-paris10.fr::CPAN - mir1.ovh.net::CPAN - rsync://ftp.crihan.fr::CPAN - ftp.gwdg.de::FTP/languages/perl/CPAN/ - ftp.leo.org::CPAN - ftp.cbn.net.id::CPAN - rsync://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN - ftp.iglu.org.il::CPAN - gusp.dyndns.org::cpan - ftp.kddlabs.co.jp::cpan - ftp.ayamura.org::pub/CPAN/ - mirror.leafbug.org::CPAN - rsync.en.com.sg::CPAN - mirror.averse.net::cpan - rsync.oss.eznetsols.org - ftp.kr.FreeBSD.org::CPAN - ftp.solnet.ch::CPAN - cpan.cdpa.nsysu.edu.tw::CPAN - cpan.teleglobe.net::CPAN - rsync://rsync.mirror.anlx.net::CPAN - ftp.sedl.org::cpan - ibiblio.org::CPAN - cpan-du.viaverio.com::CPAN - aniani.ifa.hawaii.edu::CPAN - archive.progeny.com::CPAN - rsync://slugsite.louisville.edu::CPAN - mirror.aphix.com::CPAN - cpan.teleglobe.net::CPAN - ftp.lug.udel.edu::cpan - mirrors.kernel.org::mirrors/CPAN - mirrors.phenominet.com::CPAN - cpan.pair.com::CPAN - cpan-sj.viaverio.com::CPAN - mirror.csit.fsu.edu::CPAN - csociety-ftp.ecn.purdue.edu::CPAN - -For an up-to-date listing of CPAN sites, -see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES . - -=head1 Modules: Creation, Use, and Abuse - -(The following section is borrowed directly from Tim Bunce's modules -file, available at your nearest CPAN site.) - -Perl implements a class using a package, but the presence of a -package doesn't imply the presence of a class. A package is just a -namespace. A class is a package that provides subroutines that can be -used as methods. A method is just a subroutine that expects, as its -first argument, either the name of a package (for "static" methods), -or a reference to something (for "virtual" methods). - -A module is a file that (by convention) provides a class of the same -name (sans the .pm), plus an import method in that class that can be -called to fetch exported symbols. This module may implement some of -its methods by loading dynamic C or C++ objects, but that should be -totally transparent to the user of the module. Likewise, the module -might set up an AUTOLOAD function to slurp in subroutine definitions on -demand, but this is also transparent. Only the F<.pm> file is required to -exist. See L, L, and L for details about -the AUTOLOAD mechanism. - -=head2 Guidelines for Module Creation - -=over 4 - -=item * - -Do similar modules already exist in some form? - -If so, please try to reuse the existing modules either in whole or -by inheriting useful features into a new class. If this is not -practical try to get together with the module authors to work on -extending or enhancing the functionality of the existing modules. -A perfect example is the plethora of packages in perl4 for dealing -with command line options. - -If you are writing a module to expand an already existing set of -modules, please coordinate with the author of the package. It -helps if you follow the same naming scheme and module interaction -scheme as the original author. - -=item * - -Try to design the new module to be easy to extend and reuse. - -Try to C (or C). -Remember that you can add C to individual blocks -of code that need less warnings. - -Use blessed references. Use the two argument form of bless to bless -into the class name given as the first parameter of the constructor, -e.g.,: - - sub new { - my $class = shift; - return bless {}, $class; - } - -or even this if you'd like it to be used as either a static -or a virtual method. - - sub new { - my $self = shift; - my $class = ref($self) || $self; - return bless {}, $class; - } - -Pass arrays as references so more parameters can be added later -(it's also faster). Convert functions into methods where -appropriate. Split large methods into smaller more flexible ones. -Inherit methods from other modules if appropriate. - -Avoid class name tests like: C. -Generally you can delete the C part with no harm at all. -Let the objects look after themselves! Generally, avoid hard-wired -class names as far as possible. - -Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and -C<< $r->func() >> would work (see L for more details). - -Use autosplit so little used or newly added functions won't be a -burden to programs that don't use them. Add test functions to -the module after __END__ either using AutoSplit or by saying: - - eval join('',) || die $@ unless caller(); - -Does your module pass the 'empty subclass' test? If you say -C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able -to use SUBCLASS in exactly the same way as YOURCLASS. For example, -does your application still work if you change: C<< $obj = YOURCLASS->new(); >> -into: C<< $obj = SUBCLASS->new(); >> ? - -Avoid keeping any state information in your packages. It makes it -difficult for multiple other packages to use yours. Keep state -information in objects. - -Always use B<-w>. - -Try to C (or C). -Remember that you can add C to individual blocks -of code that need less strictness. - -Always use B<-w>. - -Follow the guidelines in the perlstyle(1) manual. - -Always use B<-w>. - -=item * - -Some simple style guidelines - -The perlstyle manual supplied with Perl has many helpful points. - -Coding style is a matter of personal taste. Many people evolve their -style over several years as they learn what helps them write and -maintain good code. Here's one set of assorted suggestions that -seem to be widely used by experienced developers: - -Use underscores to separate words. It is generally easier to read -$var_names_like_this than $VarNamesLikeThis, especially for -non-native speakers of English. It's also a simple rule that works -consistently with VAR_NAMES_LIKE_THIS. - -Package/Module names are an exception to this rule. Perl informally -reserves lowercase module names for 'pragma' modules like integer -and strict. Other modules normally begin with a capital letter and -use mixed case with no underscores (need to be short and portable). - -You may find it helpful to use letter case to indicate the scope -or nature of a variable. For example: - - $ALL_CAPS_HERE constants only (beware clashes with Perl vars) - $Some_Caps_Here package-wide global/static - $no_caps_here function scope my() or local() variables - -Function and method names seem to work best as all lowercase. -e.g., C<< $obj->as_string() >>. - -You can use a leading underscore to indicate that a variable or -function should not be used outside the package that defined it. - -=item * - -Select what to export. - -Do NOT export method names! - -Do NOT export anything else by default without a good reason! - -Exports pollute the namespace of the module user. If you must -export try to use @EXPORT_OK in preference to @EXPORT and avoid -short or common names to reduce the risk of name clashes. - -Generally anything not exported is still accessible from outside the -module using the ModuleName::item_name (or C<< $blessed_ref->method >>) -syntax. By convention you can use a leading underscore on names to -indicate informally that they are 'internal' and not for public use. - -(It is actually possible to get private functions by saying: -C. But there's no way to call that -directly as a method, because a method must have a name in the symbol -table.) - -As a general rule, if the module is trying to be object oriented -then export nothing. If it's just a collection of functions then -@EXPORT_OK anything but use @EXPORT with caution. - -=item * - -Select a name for the module. - -This name should be as descriptive, accurate, and complete as -possible. Avoid any risk of ambiguity. Always try to use two or -more whole words. Generally the name should reflect what is special -about what the module does rather than how it does it. Please use -nested module names to group informally or categorize a module. -There should be a very good reason for a module not to have a nested name. -Module names should begin with a capital letter. - -Having 57 modules all called Sort will not make life easy for anyone -(though having 23 called Sort::Quick is only marginally better :-). -Imagine someone trying to install your module alongside many others. -If in any doubt ask for suggestions in comp.lang.perl.misc. - -If you are developing a suite of related modules/classes it's good -practice to use nested classes with a common prefix as this will -avoid namespace clashes. For example: Xyz::Control, Xyz::View, -Xyz::Model etc. Use the modules in this list as a naming guide. - -If adding a new module to a set, follow the original author's -standards for naming modules and the interface to methods in -those modules. - -If developing modules for private internal or project specific use, -that will never be released to the public, then you should ensure -that their names will not clash with any future public module. You -can do this either by using the reserved Local::* category or by -using a category name that includes an underscore like Foo_Corp::*. - -To be portable each component of a module name should be limited to -11 characters. If it might be used on MS-DOS then try to ensure each is -unique in the first 8 characters. Nested modules make this easier. - -=item * - -Have you got it right? - -How do you know that you've made the right decisions? Have you -picked an interface design that will cause problems later? Have -you picked the most appropriate name? Do you have any questions? - -The best way to know for sure, and pick up many helpful suggestions, -is to ask someone who knows. Comp.lang.perl.misc is read by just about -all the people who develop modules and it's the best place to ask. - -All you need to do is post a short summary of the module, its -purpose and interfaces. A few lines on each of the main methods is -probably enough. (If you post the whole module it might be ignored -by busy people - generally the very people you want to read it!) - -Don't worry about posting if you can't say when the module will be -ready - just say so in the message. It might be worth inviting -others to help you, they may be able to complete it for you! - -=item * - -README and other Additional Files. - -It's well known that software developers usually fully document the -software they write. If, however, the world is in urgent need of -your software and there is not enough time to write the full -documentation please at least provide a README file containing: - -=over 10 - -=item * - -A description of the module/package/extension etc. - -=item * - -A copyright notice - see below. - -=item * - -Prerequisites - what else you may need to have. - -=item * - -How to build it - possible changes to Makefile.PL etc. - -=item * - -How to install it. - -=item * - -Recent changes in this release, especially incompatibilities - -=item * - -Changes / enhancements you plan to make in the future. - -=back - -If the README file seems to be getting too large you may wish to -split out some of the sections into separate files: INSTALL, -Copying, ToDo etc. - -=over 4 - -=item * - -Adding a Copyright Notice. - -How you choose to license your work is a personal decision. -The general mechanism is to assert your Copyright and then make -a declaration of how others may copy/use/modify your work. - -Perl, for example, is supplied with two types of licence: The GNU GPL -and The Artistic Licence (see the files README, Copying, and Artistic, -or L and L). Larry has good reasons for NOT -just using the GNU GPL. - -My personal recommendation, out of respect for Larry, Perl, and the -Perl community at large is to state something simply like: - - Copyright (c) 1995 Your Name. All rights reserved. - This program is free software; you can redistribute it and/or - modify it under the same terms as Perl itself. - -This statement should at least appear in the README file. You may -also wish to include it in a Copying file and your source files. -Remember to include the other words in addition to the Copyright. - -=item * - -Give the module a version/issue/release number. - -To be fully compatible with the Exporter and MakeMaker modules you -should store your module's version number in a non-my package -variable called $VERSION. This should be a floating point -number with at least two digits after the decimal (i.e., hundredths, -e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version. -See L for details. - -It may be handy to add a function or method to retrieve the number. -Use the number in announcements and archive file names when -releasing the module (ModuleName-1.02.tar.Z). -See perldoc ExtUtils::MakeMaker.pm for details. - -=item * - -How to release and distribute a module. - -It's good idea to post an announcement of the availability of your -module (or the module itself if small) to the comp.lang.perl.announce -Usenet newsgroup. This will at least ensure very wide once-off -distribution. - -If possible, register the module with CPAN. You should -include details of its location in your announcement. - -Some notes about ftp archives: Please use a long descriptive file -name that includes the version number. Most incoming directories -will not be readable/listable, i.e., you won't be able to see your -file after uploading it. Remember to send your email notification -message as soon as possible after uploading else your file may get -deleted automatically. Allow time for the file to be processed -and/or check the file has been processed before announcing its -location. - -FTP Archives for Perl Modules: - -Follow the instructions and links on: - - http://www.cpan.org/modules/00modlist.long.html - http://www.cpan.org/modules/04pause.html - -or upload to one of these sites: - - https://pause.kbx.de/pause/ - http://pause.perl.org/pause/ - -and notify . - -By using the WWW interface you can ask the Upload Server to mirror -your modules from your ftp or WWW site into your own directory on -CPAN! - -Please remember to send me an updated entry for the Module list! - -=item * - -Take care when changing a released module. - -Always strive to remain compatible with previous released versions. -Otherwise try to add a mechanism to revert to the -old behavior if people rely on it. Document incompatible changes. - -=back - -=back - -=head2 Guidelines for Converting Perl 4 Library Scripts into Modules - -=over 4 - -=item * - -There is no requirement to convert anything. - -If it ain't broke, don't fix it! Perl 4 library scripts should -continue to work with no problems. You may need to make some minor -changes (like escaping non-array @'s in double quoted strings) but -there is no need to convert a .pl file into a Module for just that. - -=item * - -Consider the implications. - -All Perl applications that make use of the script will need to -be changed (slightly) if the script is converted into a module. Is -it worth it unless you plan to make other changes at the same time? - -=item * - -Make the most of the opportunity. - -If you are going to convert the script to a module you can use the -opportunity to redesign the interface. The guidelines for module -creation above include many of the issues you should consider. - -=item * - -The pl2pm utility will get you started. - -This utility will read *.pl files (given as parameters) and write -corresponding *.pm files. The pl2pm utilities does the following: - -=over 10 - -=item * - -Adds the standard Module prologue lines - -=item * - -Converts package specifiers from ' to :: - -=item * - -Converts die(...) to croak(...) - -=item * - -Several other minor changes - -=back - -Being a mechanical process pl2pm is not bullet proof. The converted -code will need careful checking, especially any package statements. -Don't delete the original .pl file till the new .pm one works! - -=back - -=head2 Guidelines for Reusing Application Code - -=over 4 - -=item * - -Complete applications rarely belong in the Perl Module Library. - -=item * - -Many applications contain some Perl code that could be reused. - -Help save the world! Share your code in a form that makes it easy -to reuse. - -=item * - -Break-out the reusable code into one or more separate module files. - -=item * - -Take the opportunity to reconsider and redesign the interfaces. - -=item * - -In some cases the 'application' can then be reduced to a small - -fragment of code built on top of the reusable modules. In these cases -the application could invoked as: - - % perl -e 'use Module::Name; method(@ARGV)' ... -or - % perl -mModule::Name ... (in perl5.002 or higher) - -=back - -=head1 NOTE - -Perl does not enforce private and public parts of its modules as you may -have been used to in other languages like C++, Ada, or Modula-17. Perl -doesn't have an infatuation with enforced privacy. It would prefer -that you stayed out of its living room because you weren't invited, not -because it has a shotgun. - -The module and its user have a contract, part of which is common law, -and part of which is "written". Part of the common law contract is -that a module doesn't pollute any namespace it wasn't asked to. The -written contract for the module (A.K.A. documentation) may make other -provisions. But then you know when you C that -you're redefining the world and willing to take the consequences. diff --git a/vms/descrip_mms.template b/vms/descrip_mms.template index f507457..d7d0615 100644 --- a/vms/descrip_mms.template +++ b/vms/descrip_mms.template @@ -440,10 +440,13 @@ pod = $(pod0) $(pod1) $(pod2) $(pod3) $(pod4) $(pod5) $(pod6) $(pod7) $(pod8) $( [.pod]perlapi.pod : embed.fnc autodoc.pl $(MINIPERL_EXE) $(MINIPERL) autodoc.pl +[.pod]perlmodlib.pod : [.pod]perlmodlib.pl MANIFEST $(MINIPERL_EXE) + $(MINIPERL) [.pod]perlmodlib.pl "-q" + [.pod]perlintern.pod : embed.fnc autodoc.pl $(MINIPERL_EXE) $(MINIPERL) autodoc.pl -[.pod]perltoc.pod : [.pod]perldelta.pod [.pod]perlapi.pod [.pod]perlintern.pod extra.pods $(PERL_EXE) +[.pod]perltoc.pod : [.pod]perldelta.pod [.pod]perlapi.pod [.pod]perlintern.pod [.pod]perlmodlib.pod extra.pods $(PERL_EXE) @ define/user_mode $(DBG)PERLSHR SYS$DISK:[]$(DBG)perlshr$(E) $(PERL) [.pod]buildtoc "-q" "--build-toc" @@ -1873,6 +1876,7 @@ clean : tidy cleantest cleanup_unpacked_files - If F$Search("[.pod]perlapi.pod").nes."" Then Delete/NoConfirm/Log [.pod]perlapi.pod;* - If F$Search("[.pod]perldelta.pod").nes."" Then Delete/NoConfirm/Log [.pod]perldelta.pod;* - If F$Search("[.pod]perlintern.pod").nes."" Then Delete/NoConfirm/Log [.pod]perlintern.pod;* + - If F$Search("[.pod]perlmodlib.pod").nes."" Then Delete/NoConfirm/Log [.pod]perlmodlib.pod;* - If F$Search("[.pod]perltoc.pod").nes."" Then Delete/NoConfirm/Log [.pod]perltoc.pod;* - @extra_pods CLEAN - If F$Search("unpushed.h").nes."" Then Delete/NoConfirm/Log unpushed.h;* diff --git a/win32/Makefile b/win32/Makefile index 5ae31e3..bff956e 100644 --- a/win32/Makefile +++ b/win32/Makefile @@ -1138,6 +1138,7 @@ utils: $(PERLEXE) $(X2P) cd ..\win32 $(PERLEXE) $(PL2BAT) $(UTILS) $(PERLEXE) ..\autodoc.pl .. + $(PERLEXE) ..\pod\perlmodlib.pl -q $(PERLEXE) ..\pod\buildtoc --build-toc -q # Note that the pod cleanup in this next section is parsed (and regenerated @@ -1206,11 +1207,11 @@ distclean: realclean perlepoc.pod perlfreebsd.pod perlhaiku.pod perlhpux.pod \ perlhurd.pod perlintern.pod perlirix.pod perljp.pod perlko.pod \ perllinux.pod perlmachten.pod perlmacos.pod perlmacosx.pod \ - perlmint.pod perlmpeix.pod perlnetware.pod perlopenbsd.pod \ - perlos2.pod perlos390.pod perlos400.pod perlplan9.pod \ - perlqnx.pod perlriscos.pod perlsolaris.pod perlsymbian.pod \ - perltoc.pod perltru64.pod perltw.pod perluts.pod perlvmesa.pod \ - perlvos.pod perlwin32.pod \ + perlmint.pod perlmodlib.pod perlmpeix.pod perlnetware.pod \ + perlopenbsd.pod perlos2.pod perlos390.pod perlos400.pod \ + perlplan9.pod perlqnx.pod perlriscos.pod perlsolaris.pod \ + perlsymbian.pod perltoc.pod perltru64.pod perltw.pod \ + perluts.pod perlvmesa.pod perlvos.pod perlwin32.pod \ pod2html pod2latex pod2man pod2text pod2usage \ podchecker podselect -cd ..\utils && del /f h2ph splain perlbug pl2pm c2ph pstruct h2xs \ diff --git a/win32/makefile.mk b/win32/makefile.mk index 2991a11..52eee6f 100644 --- a/win32/makefile.mk +++ b/win32/makefile.mk @@ -1460,6 +1460,7 @@ utils: $(PERLEXE) $(X2P) cd ..\lib && $(PERLEXE) lib_pm.PL $(PERLEXE) $(PL2BAT) $(UTILS) $(PERLEXE) ..\autodoc.pl .. + $(PERLEXE) ..\pod\perlmodlib.pl -q $(PERLEXE) ..\pod\buildtoc --build-toc -q # Note that the pod cleanup in this next section is parsed (and regenerated @@ -1528,11 +1529,11 @@ distclean: realclean perlepoc.pod perlfreebsd.pod perlhaiku.pod perlhpux.pod \ perlhurd.pod perlintern.pod perlirix.pod perljp.pod perlko.pod \ perllinux.pod perlmachten.pod perlmacos.pod perlmacosx.pod \ - perlmint.pod perlmpeix.pod perlnetware.pod perlopenbsd.pod \ - perlos2.pod perlos390.pod perlos400.pod perlplan9.pod \ - perlqnx.pod perlriscos.pod perlsolaris.pod perlsymbian.pod \ - perltoc.pod perltru64.pod perltw.pod perluts.pod perlvmesa.pod \ - perlvos.pod perlwin32.pod \ + perlmint.pod perlmodlib.pod perlmpeix.pod perlnetware.pod \ + perlopenbsd.pod perlos2.pod perlos390.pod perlos400.pod \ + perlplan9.pod perlqnx.pod perlriscos.pod perlsolaris.pod \ + perlsymbian.pod perltoc.pod perltru64.pod perltw.pod \ + perluts.pod perlvmesa.pod perlvos.pod perlwin32.pod \ pod2html pod2latex pod2man pod2text pod2usage \ podselect -cd ..\utils && del /f h2ph splain perlbug pl2pm c2ph pstruct h2xs \