From 35bf961cd9e224a6166d553c360d158bbef316a5 Mon Sep 17 00:00:00 2001 From: Jarkko Hietaniemi Date: Wed, 17 Oct 2001 02:25:01 +0000 Subject: [PATCH] Regen doc with perlmodstyle added. p4raw-id: //depot/perl@12470 --- pod/buildtoc.PL | 3 +- pod/perl.pod | 3 +- pod/perltoc.pod | 226 ++++++++++++++++++++++++++++++++++++++++++++------------ 3 files changed, 182 insertions(+), 50 deletions(-) diff --git a/pod/buildtoc.PL b/pod/buildtoc.PL index 601aa75..f9e39bc 100644 --- a/pod/buildtoc.PL +++ b/pod/buildtoc.PL @@ -149,8 +149,9 @@ if (-d "pod") { perlsec perlmod - perlmodlib perlmodinstall + perlmodlib + perlmodstyle perlnewmod perlfaq1 diff --git a/pod/perl.pod b/pod/perl.pod index d6bc93b..15e4e84 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -69,8 +69,9 @@ For ease of access, the Perl manual has been split up into several sections: perlsec Perl security perlmod Perl modules: how they work - perlmodlib Perl modules: how to write and use perlmodinstall Perl modules: how to install from CPAN + perlmodlib Perl modules: how to write and use + perlmodstyle Perl modules: how to write modules with style perlnewmod Perl modules: preparing a new module for distribution perlfaq1 General Questions About Perl diff --git a/pod/perltoc.pod b/pod/perltoc.pod index 5080243..9e11f7c 100644 --- a/pod/perltoc.pod +++ b/pod/perltoc.pod @@ -238,7 +238,7 @@ unary &, unary *, (TYPE) ?PATTERN?, m/PATTERN/cgimosx, /PATTERN/cgimosx, q/STRING/, C<'STRING'>, qq/STRING/, "STRING", qr/STRING/imosx, qx/STRING/, `STRING`, qw/STRING/, s/PATTERN/REPLACEMENT/egimosx, tr/SEARCHLIST/REPLACEMENTLIST/cds, -y/SEARCHLIST/REPLACEMENTLIST/cds +y/SEARCHLIST/REPLACEMENTLIST/cds, < the file, B the file into a directory, B the +module (sometimes unnecessary), B the module + +=back + +=item PORTABILITY + +=item HEY + +=item AUTHOR + +=item COPYRIGHT + +=back + =head2 perlmodlib - constructing new Perl modules and finding existing ones =over 4 @@ -2299,28 +2324,104 @@ Adding a Copyright Notice =back -=head2 perlmodinstall - Installing CPAN Modules +=head2 perlmodstyle - Perl module style guide =over 4 -=item DESCRIPTION +=item INTRODUCTION + +=item QUICK CHECKLIST =over 4 -=item PREAMBLE +=item Before you start -B the file, B the file into a directory, B the -module (sometimes unnecessary), B the module +=item The API + +=item Stability + +=item Documentation + +=item Release considerations =back -=item PORTABILITY +=item BEFORE YOU START WRITING A MODULE -=item HEY +=over 4 -=item AUTHOR +=item Has it been done before? -=item COPYRIGHT +=item Do one thing and do it well + +=item What's in a name? + +=back + +=item DESIGNING AND WRITING YOUR MODULE + +=over 4 + +=item To OO or not to OO? + +=item Designing your API + +Write simple routines to do simple things, Separate functionality from +output, Provide sensible shortcuts and defaults, Naming conventions, +Parameter passing + +=item Strictness and warnings + +=item Backwards compatibility + +=item Error handling and messages + +=back + +=item DOCUMENTING YOUR MODULE + +=over 4 + +=item POD + +=item README, INSTALL, release notes, changelogs + +=back + +=item RELEASE CONSIDERATIONS + +=over 4 + +=item Version numbering + +=item Pre-requisites + +=item Testing + +=item Packaging + +=item Licensing + +=back + +=item COMMON PITFALLS + +=over 4 + +=item Reinventing the wheel + +=item Trying to do too much + +=item Inappropriate documentation + +=back + +=item SEE ALSO + +L, L, L, L, Testing tools, +http://pause.perl.org/, Any good book on software engineering + +=item AUTHOR =back @@ -2462,8 +2563,8 @@ References, Tutorials, Task-Oriented, Special Topics =back -=head2 perlfaq3 - Programming Tools ($Revision: 1.1 $, $Date: 2001/09/20 -03:03:00 $) +=head2 perlfaq3 - Programming Tools ($Revision: 1.7 $, $Date: 2001/10/09 +22:17:53 $) =over 4 @@ -2509,6 +2610,9 @@ MultiEdit, SlickEdit, Bash, Ksh, Tcsh, Zsh, BBEdit and BBEdit Lite, Alpha =item How can I make my Perl program take less memory? +Don't slurp!, Use map and grep selectively, Avoid unnecessary quotes and +stringification, Pass by reference, Tie large variables to disk + =item Is it unsafe to return a pointer to local data? =item How can I free an array or hash so my program shrinks? @@ -2547,8 +2651,8 @@ mean? =back -=head2 perlfaq4 - Data Manipulation ($Revision: 1.1 $, $Date: 2001/09/20 -03:03:00 $) +=head2 perlfaq4 - Data Manipulation ($Revision: 1.5 $, $Date: 2001/10/12 +15:20:13 $) =over 4 @@ -2757,8 +2861,8 @@ array of hashes or arrays? =back -=head2 perlfaq5 - Files and Formats ($Revision: 1.1 $, $Date: 2001/09/20 -03:03:00 $) +=head2 perlfaq5 - Files and Formats ($Revision: 1.2 $, $Date: 2001/09/26 +10:44:41 $) =over 4 @@ -3123,7 +3227,7 @@ search path? =back -=head2 perlfaq9 - Networking ($Revision: 1.1 $, $Date: 2001/09/20 03:03:00 +=head2 perlfaq9 - Networking ($Revision: 1.2 $, $Date: 2001/09/28 06:40:07 $) =over 4 @@ -3132,6 +3236,8 @@ $) =over 4 +=item What is the correct form of response from a CGI script? + =item My CGI script runs from the command line but not the browser. (500 Server Error) @@ -3936,19 +4042,19 @@ PL_sv_yes, POPi, POPl, POPn, POPp, POPpbytex, POPpx, POPs, PUSHi, PUSHMARK, PUSHn, PUSHp, PUSHs, PUSHu, PUTBACK, Renew, Renewc, require_pv, RETVAL, Safefree, savepv, savepvn, SAVETMPS, scan_bin, scan_hex, scan_oct, sharedsv_find, sharedsv_init, sharedsv_lock, sharedsv_new, -sharedsv_thrcnt_dec, sharedsv_thrcnt_inc, sharedsv_unlock, SP, SPAGAIN, ST, -strEQ, strGE, strGT, strLE, strLT, strNE, strnEQ, strnNE, StructCopy, -SvCUR, SvCUR_set, SvEND, SvGETMAGIC, SvGROW, SvIOK, SvIOKp, SvIOK_notUV, -SvIOK_off, SvIOK_on, SvIOK_only, SvIOK_only_UV, SvIOK_UV, SvIV, SvIVX, -SvIVx, SvLEN, SvNIOK, SvNIOKp, SvNIOK_off, SvNOK, SvNOKp, SvNOK_off, -SvNOK_on, SvNOK_only, SvNV, SvNVx, SvNVX, SvOK, SvOOK, SvPOK, SvPOKp, -SvPOK_off, SvPOK_on, SvPOK_only, SvPOK_only_UTF8, SvPV, SvPVbyte, +sharedsv_thrcnt_dec, sharedsv_thrcnt_inc, sharedsv_unlock, sortsv, SP, +SPAGAIN, ST, strEQ, strGE, strGT, strLE, strLT, strNE, strnEQ, strnNE, +StructCopy, SvCUR, SvCUR_set, SvEND, SvGETMAGIC, SvGROW, SvIOK, SvIOKp, +SvIOK_notUV, SvIOK_off, SvIOK_on, SvIOK_only, SvIOK_only_UV, SvIOK_UV, +SvIV, SvIVX, SvIVx, SvLEN, SvNIOK, SvNIOKp, SvNIOK_off, SvNOK, SvNOKp, +SvNOK_off, SvNOK_on, SvNOK_only, SvNV, SvNVX, SvNVx, SvOK, SvOOK, SvPOK, +SvPOKp, SvPOK_off, SvPOK_on, SvPOK_only, SvPOK_only_UTF8, SvPV, SvPVbyte, SvPVbytex, SvPVbytex_force, SvPVbyte_force, SvPVbyte_nolen, SvPVutf8, -SvPVutf8x, SvPVutf8x_force, SvPVutf8_force, SvPVutf8_nolen, SvPVX, SvPVx, +SvPVutf8x, SvPVutf8x_force, SvPVutf8_force, SvPVutf8_nolen, SvPVx, SvPVX, SvPV_force, SvPV_force_nomg, SvPV_nolen, SvREFCNT, SvREFCNT_dec, SvREFCNT_inc, SvROK, SvROK_off, SvROK_on, SvRV, SvSETMAGIC, SvSetMagicSV, SvSetMagicSV_nosteal, SvSetSV, SvSetSV_nosteal, SvSTASH, SvTAINT, -SvTAINTED, SvTAINTED_off, SvTAINTED_on, SvTRUE, svtype, SvTYPE, SVt_IV, +SvTAINTED, SvTAINTED_off, SvTAINTED_on, SvTRUE, SvTYPE, svtype, SVt_IV, SVt_NV, SVt_PV, SVt_PVAV, SVt_PVCV, SVt_PVHV, SVt_PVMG, SvUOK, SvUPGRADE, SvUTF8, SvUTF8_off, SvUTF8_on, SvUV, SvUVX, SvUVx, sv_2bool, sv_2cv, sv_2io, sv_2iv, sv_2mortal, sv_2nv, sv_2pvbyte, sv_2pvbyte_nolen, @@ -6072,6 +6178,8 @@ Source, Compiled Module Source, Perl Modules/Scripts =over 4 +=item Using perl as shipped with HP-UX + =item Compiling Perl 5 on HP-UX =item PA-RISC @@ -6082,6 +6190,8 @@ Source, Compiled Module Source, Perl Modules/Scripts =item PA-RISC 2.0 +=item Itanium + =item Portability Between PA-RISC Versions =item Itanium Processor Family and HP-UX @@ -6106,6 +6216,8 @@ Source, Compiled Module Source, Perl Modules/Scripts =back +=item nss_delete core dump from op/pwent or op/grent + =item AUTHOR =item DATE @@ -6669,6 +6781,8 @@ DATAMODEL_NATIVE specified", sh: ar: not found =item op/stat.t test 4 in Solaris +=item nss_delete core dump from op/pwent or op/grent + =back =item PREBUILT BINARIES OF PERL FOR SOLARIS. @@ -6938,7 +7052,8 @@ leaks! =item BUGS -creating a thread from within a thread is unsafe under win32 +creating a thread from within a thread is unsafe under win32, +PERL_OLD_SIGNALS are not threadsafe, will not be =item SEE ALSO @@ -7425,7 +7540,8 @@ leaks! =item BUGS -creating a thread from within a thread is unsafe under win32 +creating a thread from within a thread is unsafe under win32, +PERL_OLD_SIGNALS are not threadsafe, will not be =item SEE ALSO @@ -9315,7 +9431,9 @@ $Data::Dumper::Toaster I $I->Toaster(I<[NEWVAL]>), $Data::Dumper::Deepcopy I $I->Deepcopy(I<[NEWVAL]>), $Data::Dumper::Quotekeys I $I->Quotekeys(I<[NEWVAL]>), $Data::Dumper::Bless I $I->Bless(I<[NEWVAL]>), -$Data::Dumper::Maxdepth I $I->Maxdepth(I<[NEWVAL]>) +$Data::Dumper::Maxdepth I $I->Maxdepth(I<[NEWVAL]>), +$Data::Dumper::Useperl I $I->Useperl(I<[NEWVAL]>), +$Data::Dumper::Sortkeys I $I->Sortkeys(I<[NEWVAL]>) =item Exports @@ -9487,8 +9605,8 @@ $md5->addfile($io_handle), $md5->digest, $md5->hexdigest, $md5->b64digest =item Creation C, C, C, C, C, -C, C, C, C, C, -C, C, unctrl, subdump, bareStringify, quoteHighBit, +C, C, C, C, C, +C, C, unctrl, subdump, bareStringify, quoteHighBit, stopDbSignal =item Methods @@ -9785,7 +9903,7 @@ test_f file =item USAGE -IV, UV, NV, PV, PVN, PVN, YES, NO, UNDEF +IV, UV, NV, PV, PVN, SV, YES, NO, UNDEF =item FUNCTIONS @@ -9807,6 +9925,8 @@ params WHAT dump_names +dogfood + C_constant, name, type, value, macro, default, pre, post, def_pre =item def_post @@ -9814,6 +9934,8 @@ XS_constant PACKAGE, TYPES, SUBNAME, C_SUBNAME autoload PACKAGE, VERSION, AUTOLOADER +WriteMakefileSnippet + WriteConstants ATTRIBUTE =E VALUE [, ...], NAME, DEFAULT_TYPE, BREAKOUT_AT, NAMES, C_FILE, XS_FILE, SUBNAME, C_SUBNAME @@ -10401,8 +10523,8 @@ MAKEAPERL, MAKEFILE, MAN1PODS, MAN3PODS, MAP_TARGET, MYEXTLIB, NAME, NEEDS_LINKING, NOECHO, NORECURS, NO_VC, OBJECT, OPTIMIZE, PERL, PERL_CORE, PERLMAINCC, PERL_ARCHLIB, PERL_LIB, PERL_MALLOC_OK, PERLRUN, PERM_RW, PERM_RWX, PL_FILES, PM, PMLIBDIRS, PM_FILTER, POLLUTE, PPM_INSTALL_EXEC, -PPM_INSTALL_SCRIPT, PREFIX, PREREQ_PM, SKIP, TEST_LIBS, VERSION, -VERSION_FROM, XS, XSOPT, XSPROTOARG, XS_VERSION +PPM_INSTALL_SCRIPT, PREFIX, PREREQ_FATAL, PREREQ_PM, SKIP, TEST_LIBS, +VERSION, VERSION_FROM, XS, XSOPT, XSPROTOARG, XS_VERSION =item Additional lowercase attributes @@ -10629,6 +10751,8 @@ rmscopy($from,$to[,$date_flag]) =item DESCRIPTION +=item NOTES + =item EXPORTS (by request only) =item BUGS @@ -10707,7 +10831,7 @@ C, C canonpath, catdir, catfile, curdir, devnull, rootdir, tmpdir, updir, no_upwards, case_tolerant, file_name_is_absolute, path, join, splitpath, -splitdir, catpath, abs2rel, rel2abs +splitdir, catpath(), abs2rel, rel2abs() =item SEE ALSO @@ -10731,7 +10855,7 @@ tmpdir path -canonpath +canonpath() splitpath @@ -10741,7 +10865,7 @@ catpath abs2rel -rel2abs +rel2abs() =over 4 @@ -10767,7 +10891,7 @@ rel2abs =back -=head2 File::Spec::Mac - File::Spec for MacOS +=head2 File::Spec::Mac - File::Spec for Mac OS (Classic) =over 4 @@ -10781,7 +10905,7 @@ canonpath =back -catdir +catdir() catfile @@ -10803,7 +10927,7 @@ splitpath splitdir -catpath +catpath() abs2rel @@ -10811,6 +10935,8 @@ rel2abs =over 4 +=item AUTHORS + =item SEE ALSO =back @@ -10836,11 +10962,11 @@ modules =item METHODS -canonpath +canonpath() =back -catdir +catdir() catfile @@ -10868,11 +10994,11 @@ splitpath splitdir -catpath +catpath() abs2rel -rel2abs +rel2abs() =over 4 @@ -11180,6 +11306,8 @@ B<$_>, B<$status>, B and B, B =item EXPORTABLE VARIABLES +=item KNOWN ISSUES + =item KNOWN BUGS =item AUTHORS @@ -15641,6 +15769,8 @@ unexpand(1) =item DESCRIPTION +=item OVERRIDES + =item EXAMPLE =item AUTHOR -- 2.7.4