diff options
Diffstat (limited to 'pod')
| -rw-r--r-- | pod/perl.pod | 60 | ||||
| -rw-r--r-- | pod/perldelta.pod | 17 | ||||
| -rw-r--r-- | pod/perlguts.pod | 162 | ||||
| -rw-r--r-- | pod/perllocale.pod | 2 | ||||
| -rw-r--r-- | pod/perlrun.pod | 68 | ||||
| -rw-r--r-- | pod/perlsec.pod | 25 | ||||
| -rw-r--r-- | pod/perltoc.pod | 79 | ||||
| -rw-r--r-- | pod/pod2man.PL | 23 |
8 files changed, 315 insertions, 121 deletions
diff --git a/pod/perl.pod b/pod/perl.pod index e306037551..99f996f130 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -42,7 +42,6 @@ of sections: perlbot Perl OO tricks and examples perlipc Perl interprocess communication - perlbug Perl bug reports howto perldebug Perl debugging perldiag Perl diagnostic messages perlsec Perl security @@ -224,64 +223,7 @@ Ok, that's I<definitely> enough hype. =head1 ENVIRONMENT -=over 12 - -=item HOME - -Used if chdir has no argument. - -=item LOGDIR - -Used if chdir has no argument and HOME is not set. - -=item PATH - -Used in executing subprocesses, and in finding the script if B<-S> is -used. - -=item PERL5LIB - -A colon-separated list of directories in which to look for Perl library -files before looking in the standard library and the current -directory. If PERL5LIB is not defined, PERLLIB is used. When running -taint checks (because the script was running setuid or setgid, or the -B<-T> switch was used), neither variable is used. The script should -instead say - - use lib "/my/directory"; - -=item PERL5DB - -The command used to get the debugger code. If unset, uses - - BEGIN { require 'perl5db.pl' } - -=item PERL_DESTRUCT_LEVEL - -Relevant only if your perl executable was built with B<-DDEBUGGING>, -this controls the behavior of global destruction of objects and other -references. - -=item PERLLIB - -A colon-separated list of directories in which to look for Perl library -files before looking in the standard library and the current -directory. If PERL5LIB is defined, PERLLIB is not used. - -=back - -Perl also has environment variables that control how Perl handles data -specific to particular natural languages. See L<perllocale>. - -Apart from these, Perl uses no other environment variables, except -to make them available to the script being executed, and to child -processes. However, scripts running setuid would do well to execute -the following lines before doing anything else, just to keep people -honest: - - $ENV{'PATH'} = '/bin:/usr/bin'; # or whatever you need - $ENV{'SHELL'} = '/bin/sh' if defined $ENV{'SHELL'}; - $ENV{'IFS'} = '' if defined $ENV{'IFS'}; +See L<perlrun>. =head1 AUTHOR diff --git a/pod/perldelta.pod b/pod/perldelta.pod index 23f216fce6..bfdf9031ef 100644 --- a/pod/perldelta.pod +++ b/pod/perldelta.pod @@ -671,6 +671,17 @@ C<perl_call_sv> is Perl's producing an "Undefined subroutine called" error on the I<second> call to a given method (since there is no cache on the first call). +=item Extended API for manipulating hashes + +Internal handling of hash keys has changed. The old hashtable API is +still fully supported, and will likely remain so. The additions to the +API allow passing keys as C<SV*>s, so that C<tied> hashes can be given +real scalars as keys rather than plain strings (non-tied hashes still +can only use strings as keys). New extensions must use the new hash +access functions and macros if they wish to use C<SV*> keys. These +additions also make it feasible to manipulate C<HE*>s (hash entries), +which can be more efficient. See L<perlguts> for details. + =back =head1 Documentation Changes @@ -680,10 +691,6 @@ new pods are included in section 1: =over -=item L<perlbug> - -A "howto" on reporting perl bugs. - =item L<perldelta> This document. @@ -1023,7 +1030,7 @@ Home Page. If you believe you have an unreported bug, please run the B<perlbug> program included with your release. Make sure you trim your bug down to a tiny but sufficient test case. Your bug report, along -with the output of C<perl -V>, will be sent off to perlbug@perl.com +with the output of C<perl -V>, will be sent off to F<perlbug@perl.com> to be analysed by the Perl porting team. =head1 SEE ALSO diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 77acc98aae..95bd4eccbd 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -322,6 +322,48 @@ The hash algorithm is defined in the C<PERL_HASH(hash, key, klen)> macro: while (i--) hash = hash * 33 + *s++; +=head2 Hash API Extensions + +Beginning with version 5.004, the following functions are also supported: + + HE* hv_fetch_ent (HV* tb, SV* key, I32 lval, U32 hash); + HE* hv_store_ent (HV* tb, SV* key, SV* val, U32 hash); + + bool hv_exists_ent (HV* tb, SV* key, U32 hash); + SV* hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash); + + SV* hv_iterkeysv (HE* entry); + +Note that these functions take C<SV*> keys, which simplifies writing +of extension code that deals with hash structures. These functions +also allow passing of C<SV*> keys to C<tie> functions without forcing +you to stringify the keys (unlike the previous set of functions). + +They also return and accept whole hash entries (C<HE*>), making their +use more efficient (since the hash number for a particular string +doesn't have to be recomputed every time). See L<API LISTING> later in +this document for detailed descriptions. + +The following macros must always be used to access the contents of hash +entries. Note that the arguments to these macros must be simple +variables, since they may get evaluated more than once. See +L<API LISTING> later in this document for detailed descriptions of these +macros. + + HePV(HE* he, STRLEN len) + HeVAL(HE* he) + HeHASH(HE* he) + HeSVKEY(HE* he) + HeSVKEY_force(HE* he) + HeSVKEY_set(HE* he, SV* sv) + +These two lower level macros are defined, but must only be used when +dealing with keys that are not C<SV*>s: + + HeKEY(HE* he) + HeKLEN(HE* he) + + =head2 References References are a special type of scalar that point to other data types @@ -1392,6 +1434,12 @@ statement (or thereabouts) with C<sv_2mortal>. See C<hv_iternext>. void he_delayfree _((HV* hv, HE* hent)); +=item HEf_SVKEY + +This flag, used in the length slot of hash entries and magic +structures, specifies the structure contains a C<SV*> pointer where a +C<char*> pointer is to be expected. (For information only--not to be used). + =item he_free Releases a hash entry, such as while iterating though the hash. See @@ -1399,6 +1447,71 @@ C<hv_iternext>. void he_free _((HV* hv, HE* hent)); +=item HeHASH + +Returns the computed hash (type C<U32>) stored in the hash entry. + + HeHASH(HE* he) + +=item HeKEY + +Returns the actual pointer stored in the key slot of the hash entry. +The pointer may be either C<char*> or C<SV*>, depending on the value of +C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros +are usually preferable for finding the value of a key. + + HeKEY(HE* he) + +=item HeKLEN + +If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry +holds an C<SV*> key. Otherwise, holds the actual length of the key. +Can be assigned to. The C<HePV()> macro is usually preferable for finding +key lengths. + + HeKLEN(HE* he) + +=item HePV + +Returns the key slot of the hash entry as a C<char*> value, doing any +necessary dereferencing of possibly C<SV*> keys. The length of +the string is placed in C<len> (this is a macro, so do I<not> use +C<&len>). If you do not care about what the length of the key is, +you may use the global variable C<na>. Remember though, that hash +keys in perl are free to contain embedded nulls, so using C<strlen()> +or similar is not a good way to find the length of hash keys. +This is very similar to the C<SvPV()> macro described elsewhere in +this document. + + HePV(HE* he, STRLEN len) + +=item HeSVKEY + +Returns the key as an C<SV*>, or C<Nullsv> if the hash entry +does not contain an C<SV*> key. + + HeSVKEY(HE* he) + +=item HeSVKEY_force + +Returns the key as an C<SV*>. Will create and return a temporary +mortal C<SV*> if the hash entry contains only a C<char*> key. + + HeSVKEY_force(HE* he) + +=item HeSVKEY_set + +Sets the key to a given C<SV*>, taking care to set the appropriate flags +to indicate the presence of an C<SV*> key, and returns the same C<SV*>. + + HeSVKEY_set(HE* he, SV* sv) + +=item HeVAL + +Returns the value slot (type C<SV*>) stored in the hash entry. + + HeVAL(HE* he) + =item hv_clear Clears a hash, making it empty. @@ -1414,6 +1527,15 @@ returned. SV* hv_delete _((HV* tb, char* key, U32 klen, I32 flags)); +=item hv_delete_ent + +Deletes a key/value pair in the hash. The value SV is removed from the hash +and returned to the caller. The C<flags> value will normally be zero; if set +to G_DISCARD then null will be returned. C<hash> can be a valid pre-computed +hash value, or 0 to ask for it to be computed. + + SV* hv_delete_ent _((HV* tb, SV* key, I32 flags, U32 hash)); + =item hv_exists Returns a boolean indicating whether the specified hash key exists. The @@ -1421,6 +1543,13 @@ C<klen> is the length of the key. bool hv_exists _((HV* tb, char* key, U32 klen)); +=item hv_exists_ent + +Returns a boolean indicating whether the specified hash key exists. C<hash> +can be a valid pre-computed hash value, or 0 to ask for it to be computed. + + bool hv_exists_ent _((HV* tb, SV* key, U32 hash)); + =item hv_fetch Returns the SV which corresponds to the specified key in the hash. The @@ -1430,6 +1559,18 @@ dereferencing it to a C<SV*>. SV** hv_fetch _((HV* tb, char* key, U32 klen, I32 lval)); +=item hv_fetch_ent + +Returns the hash entry which corresponds to the specified key in the hash. +C<hash> must be a valid pre-computed hash number for the given C<key>, or +0 if you want the function to compute it. IF C<lval> is set then the +fetch will be part of a store. Make sure the return value is non-null +before accessing it. The return value when C<tb> is a tied hash +is a pointer to a static location, so be sure to make a copy of the +structure if you need to store it somewhere. + + HE* hv_fetch_ent _((HV* tb, SV* key, I32 lval, U32 hash)); + =item hv_iterinit Prepares a starting point to traverse a hash table. @@ -1443,6 +1584,14 @@ C<hv_iterinit>. char* hv_iterkey _((HE* entry, I32* retlen)); +=item hv_iterkeysv + +Returns the key as an C<SV*> from the current position of the hash +iterator. The return value will always be a mortal copy of the +key. Also see C<hv_iterinit>. + + SV* hv_iterkeysv _((HE* entry)); + =item hv_iternext Returns entries from a hash iterator. See C<hv_iterinit>. @@ -1485,6 +1634,17 @@ original C<SV*>. SV** hv_store _((HV* tb, char* key, U32 klen, SV* val, U32 hash)); +=item hv_store_ent + +Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash> +parameter is the pre-computed hash value; if it is zero then Perl will +compute it. The return value is the new hash entry so created. It will be +null if the operation failed or if the entry was stored in a tied hash. +Otherwise the contents of the return value can be accessed using the +C<He???> macros described here. + + HE* hv_store_ent _((HV* tb, SV* key, SV* val, U32 hash)); + =item hv_undef Undefines the hash. @@ -2748,4 +2908,4 @@ API Listing by Dean Roehrich <roehrich@cray.com>. =head1 DATE -Version 31: 1997/1/27 +Version 31.1: 1997/2/25 diff --git a/pod/perllocale.pod b/pod/perllocale.pod index 41a0bc5d8b..15138677d2 100644 --- a/pod/perllocale.pod +++ b/pod/perllocale.pod @@ -778,7 +778,7 @@ In certain system environments the operating system's locale support is broken and cannot be fixed or used by Perl. Such deficiencies can and will result in mysterious hangs and/or Perl core dumps when the C<use locale> is in effect. When confronted with such a system, -please report in excruciating detail to C<perlbug@perl.com>, and +please report in excruciating detail to F<perlbug@perl.com>, and complain to your vendor: maybe some bug fixes exist for these problems in your operating system. Sometimes such bug fixes are called an operating system upgrade. diff --git a/pod/perlrun.pod b/pod/perlrun.pod index df606bf0ea..f90e642d40 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -439,5 +439,73 @@ terminated with C<__END__> if there is trailing garbage to be ignored (the script can process any or all of the trailing garbage via the DATA filehandle if desired). +=back + +=head1 ENVIRONMENT + +=over 12 + +=item HOME + +Used if chdir has no argument. + +=item LOGDIR + +Used if chdir has no argument and HOME is not set. + +=item PATH + +Used in executing subprocesses, and in finding the script if B<-S> is +used. + +=item PERL5LIB + +A colon-separated list of directories in which to look for Perl library +files before looking in the standard library and the current +directory. If PERL5LIB is not defined, PERLLIB is used. When running +taint checks (because the script was running setuid or setgid, or the +B<-T> switch was used), neither variable is used. The script should +instead say + + use lib "/my/directory"; + +=item PERLLIB + +A colon-separated list of directories in which to look for Perl library +files before looking in the standard library and the current directory. +If PERL5LIB is defined, PERLLIB is not used. + +=item PERL5DB + +The command used to load the debugger code. The default is: + + BEGIN { require 'perl5db.pl' } + +=item PERL_DEBUG_MSTATS + +Relevant only if your perl executable was built with B<-DDEBUGGING_MSTATS>, +if set, this causes memory statistics to be dumped after execution. If set +to an integer greater than one, also causes memory statistics to be dumped +after compilation. + +=item PERL_DESTRUCT_LEVEL + +Relevant only if your perl executable was built with B<-DDEBUGGING>, +this controls the behavior of global destruction of objects and other +references. =back + +Perl also has environment variables that control how Perl handles data +specific to particular natural languages. See L<perllocale>. + +Apart from these, Perl uses no other environment variables, except +to make them available to the script being executed, and to child +processes. However, scripts running setuid would do well to execute +the following lines before doing anything else, just to keep people +honest: + + $ENV{'PATH'} = '/bin:/usr/bin'; # or whatever you need + $ENV{'SHELL'} = '/bin/sh' if defined $ENV{'SHELL'}; + $ENV{'IFS'} = '' if defined $ENV{'IFS'}; + diff --git a/pod/perlsec.pod b/pod/perlsec.pod index 3e44e5bea4..6089431a2a 100644 --- a/pod/perlsec.pod +++ b/pod/perlsec.pod @@ -20,10 +20,11 @@ mode explicitly by using the B<-T> command line flag. This flag is I<strongly> suggested for server programs and any program run on behalf of someone else, such as a CGI script. -While in this mode, Perl takes special precautions called I<taint checks> to -prevent both obvious and subtle traps. Some of these checks are reasonably -simple, such as not blindly using the PATH inherited from one's parent -process. Other checks, however, are best supported by the language itself, +While in this mode, Perl takes special precautions called I<taint +checks> to prevent both obvious and subtle traps. Some of these checks +are reasonably simple, such as verifying that path directories aren't +writable by others; careful programmers have always used checks like +these. Other checks, however, are best supported by the language itself, and it is these checks especially that contribute to making a setuid Perl program more secure than the corresponding C program. @@ -155,13 +156,15 @@ UNIX-like environments that support #! and setuid or setgid scripts.) =head2 Cleaning Up Your Path For "Insecure C<$ENV{PATH}>" messages, you need to set C<$ENV{'PATH'}> to a -known value. You may be surprised to get this message even if the pathname -to your executable is fully qualified. This is I<not> generated because you -didn't supply a full path to the program; instead, it's generated because -you never set your PATH environment variable. Because Perl can't guarantee -that the executable in question isn't itself going to turn around and -execute some other program that is dependent on your PATH, it makes sure you -set the PATH. +known value, and each directory in the path must be non-writable by others +than its owner and group. You may be surprised to get this message even +if the pathname to your executable is fully qualified. This is I<not> +generated because you didn't supply a full path to the program; instead, +it's generated because you never set your PATH environment variable, or +you didn't set it to something that was safe. Because Perl can't +guarantee that the executable in question isn't itself going to turn +around and execute some other program that is dependent on your PATH, it +makes sure you set the PATH. It's also possible to get into trouble with other operations that don't care whether they use tainted values. Make judicious use of the file diff --git a/pod/perltoc.pod b/pod/perltoc.pod index 01a03f3e05..551f444c31 100644 --- a/pod/perltoc.pod +++ b/pod/perltoc.pod @@ -26,8 +26,6 @@ expression enhancements, Innumerable Unbundled Modules, Compilability =item ENVIRONMENT -HOME, LOGDIR, PATH, PERL5LIB, PERL5DB, PERL_DESTRUCT_LEVEL, PERLLIB - =item AUTHOR =item FILES @@ -126,12 +124,12 @@ C<void> XSUBs now default to returning nothing =item C Language API Changes -C<gv_fetchmethod> and C<perl_call_sv> +C<gv_fetchmethod> and C<perl_call_sv>, Extended API for manipulating hashes =item Documentation Changes -L<perlbug>, L<perldelta>, L<perllocale>, L<perltoot>, L<perlapio>, -L<perldebug>, L<perlsec> +L<perldelta>, L<perllocale>, L<perltoot>, L<perlapio>, L<perldebug>, +L<perlsec> =item New Diagnostics @@ -323,6 +321,11 @@ B<-T>, B<-u>, B<-U>, B<-v>, B<-V>, B<-V:>I<name>, B<-w>, B<-x> I<directory> =back +=item ENVIRONMENT + +HOME, LOGDIR, PATH, PERL5LIB, PERLLIB, PERL5DB, PERL_DEBUG_MSTATS, +PERL_DESTRUCT_LEVEL + =head2 perlfunc - Perl builtin functions =item DESCRIPTION @@ -1434,6 +1437,8 @@ B<PerlIO_get_base(f)>, B<PerlIO_get_bufsiz(f)> =item Working with HV's +=item Hash API Extensions + =item References =item Blessed References and Class Objects @@ -1501,35 +1506,41 @@ av_shift, av_store, av_undef, av_unshift, CLASS, Copy, croak, CvSTASH, DBsingle, DBsub, DBtrace, dMARK, dORIGMARK, dowarn, dSP, dXSARGS, dXSI32, dXSI32, ENTER, EXTEND, FREETMPS, G_ARRAY, G_DISCARD, G_EVAL, GIMME, G_NOARGS, G_SCALAR, gv_fetchmeth, gv_fetchmethod, gv_stashpv, gv_stashsv, -GvSV, he_delayfree, he_free, hv_clear, hv_delete, hv_exists, hv_fetch, -hv_iterinit, hv_iterkey, hv_iternext, hv_iternextsv, hv_iterval, hv_magic, -HvNAME, hv_store, hv_undef, isALNUM, isALPHA, isDIGIT, isLOWER, isSPACE, -isUPPER, items, ix, LEAVE, MARK, mg_clear, mg_copy, mg_find, mg_free, -mg_get, mg_len, mg_magical, mg_set, Move, na, New, Newc, Newz, newAV, -newHV, newRV_inc, newRV_noinc, newSV, newSViv, newSVnv, newSVpv, newSVrv, -newSVsv, newXS, newXSproto, Nullav, Nullch, Nullcv, Nullhv, Nullsv, -ORIGMARK, perl_alloc, perl_call_argv, perl_call_method, perl_call_pv, -perl_call_sv, perl_construct, perl_destruct, perl_eval_sv, perl_free, -perl_get_av, perl_get_cv, perl_get_hv, perl_get_sv, perl_parse, -perl_require_pv, perl_run, POPi, POPl, POPp, POPn, POPs, PUSHMARK, PUSHi, -PUSHn, PUSHp, PUSHs, PUTBACK, Renew, Renewc, RETVAL, safefree, safemalloc, -saferealloc, savepv, savepvn, SAVETMPS, SP, SPAGAIN, ST, strEQ, strGE, -strGT, strLE, strLT, strNE, strnEQ, strnNE, sv_2mortal, sv_bless, sv_catpv, -sv_catpvn, sv_catsv, sv_cmp, sv_cmp, SvCUR, SvCUR_set, sv_dec, sv_dec, -SvEND, sv_eq, SvGROW, sv_grow, sv_inc, SvIOK, SvIOK_off, SvIOK_on, -SvIOK_only, SvIOK_only, SvIOKp, sv_isa, SvIV, sv_isobject, SvIVX, SvLEN, -sv_len, sv_len, sv_magic, sv_mortalcopy, SvOK, sv_newmortal, sv_no, SvNIOK, -SvNIOK_off, SvNIOKp, SvNOK, SvNOK_off, SvNOK_on, SvNOK_only, SvNOK_only, -SvNOKp, SvNV, SvNVX, SvPOK, SvPOK_off, SvPOK_on, SvPOK_only, SvPOK_only, -SvPOKp, SvPV, SvPVX, SvREFCNT, SvREFCNT_dec, SvREFCNT_inc, SvROK, -SvROK_off, SvROK_on, SvRV, sv_setiv, sv_setnv, sv_setpv, sv_setpvn, -sv_setref_iv, sv_setref_nv, sv_setref_pv, sv_setref_pvn, sv_setsv, SvSTASH, -SVt_IV, SVt_PV, SVt_PVAV, SVt_PVCV, SVt_PVHV, SVt_PVMG, SVt_NV, SvTRUE, -SvTYPE, svtype, SvUPGRADE, sv_upgrade, sv_undef, sv_unref, sv_usepvn, -sv_yes, THIS, toLOWER, toUPPER, warn, XPUSHi, XPUSHn, XPUSHp, XPUSHs, XS, -XSRETURN, XSRETURN_EMPTY, XSRETURN_IV, XSRETURN_NO, XSRETURN_NV, -XSRETURN_PV, XSRETURN_UNDEF, XSRETURN_YES, XST_mIV, XST_mNV, XST_mNO, -XST_mPV, XST_mUNDEF, XST_mYES, XS_VERSION, XS_VERSION_BOOTCHECK, Zero +GvSV, he_delayfree, HEf_SVKEY, he_free, HeHASH, HeKEY, HeKLEN, HePV, +HeSVKEY, HeSVKEY_force, HeSVKEY_set, HeVAL, hv_clear, hv_delete, +hv_delete_ent, hv_exists, hv_exists_ent, hv_fetch, hv_fetch_ent, +hv_iterinit, hv_iterkey, hv_iterkeysv +Returns the key as an C<SV*> from the current position of the hash +iterator. The return value will always be a mortal copy of the +key. Also see C<hv_iterinit>, hv_iternext, hv_iternextsv, hv_iterval, +hv_magic, HvNAME, hv_store, hv_store_ent, hv_undef, isALNUM, isALPHA, +isDIGIT, isLOWER, isSPACE, isUPPER, items, ix, LEAVE, MARK, mg_clear, +mg_copy, mg_find, mg_free, mg_get, mg_len, mg_magical, mg_set, Move, na, +New, Newc, Newz, newAV, newHV, newRV_inc, newRV_noinc, newSV, newSViv, +newSVnv, newSVpv, newSVrv, newSVsv, newXS, newXSproto, Nullav, Nullch, +Nullcv, Nullhv, Nullsv, ORIGMARK, perl_alloc, perl_call_argv, +perl_call_method, perl_call_pv, perl_call_sv, perl_construct, +perl_destruct, perl_eval_sv, perl_free, perl_get_av, perl_get_cv, +perl_get_hv, perl_get_sv, perl_parse, perl_require_pv, perl_run, POPi, +POPl, POPp, POPn, POPs, PUSHMARK, PUSHi, PUSHn, PUSHp, PUSHs, PUTBACK, +Renew, Renewc, RETVAL, safefree, safemalloc, saferealloc, savepv, savepvn, +SAVETMPS, SP, SPAGAIN, ST, strEQ, strGE, strGT, strLE, strLT, strNE, +strnEQ, strnNE, sv_2mortal, sv_bless, sv_catpv, sv_catpvn, sv_catsv, +sv_cmp, sv_cmp, SvCUR, SvCUR_set, sv_dec, sv_dec, SvEND, sv_eq, SvGROW, +sv_grow, sv_inc, SvIOK, SvIOK_off, SvIOK_on, SvIOK_only, SvIOK_only, +SvIOKp, sv_isa, SvIV, sv_isobject, SvIVX, SvLEN, sv_len, sv_len, sv_magic, +sv_mortalcopy, SvOK, sv_newmortal, sv_no, SvNIOK, SvNIOK_off, SvNIOKp, +SvNOK, SvNOK_off, SvNOK_on, SvNOK_only, SvNOK_only, SvNOKp, SvNV, SvNVX, +SvPOK, SvPOK_off, SvPOK_on, SvPOK_only, SvPOK_only, SvPOKp, SvPV, SvPVX, +SvREFCNT, SvREFCNT_dec, SvREFCNT_inc, SvROK, SvROK_off, SvROK_on, SvRV, +sv_setiv, sv_setnv, sv_setpv, sv_setpvn, sv_setref_iv, sv_setref_nv, +sv_setref_pv, sv_setref_pvn, sv_setsv, SvSTASH, SVt_IV, SVt_PV, SVt_PVAV, +SVt_PVCV, SVt_PVHV, SVt_PVMG, SVt_NV, SvTRUE, SvTYPE, svtype, SvUPGRADE, +sv_upgrade, sv_undef, sv_unref, sv_usepvn, sv_yes, THIS, toLOWER, toUPPER, +warn, XPUSHi, XPUSHn, XPUSHp, XPUSHs, XS, XSRETURN, XSRETURN_EMPTY, +XSRETURN_IV, XSRETURN_NO, XSRETURN_NV, XSRETURN_PV, XSRETURN_UNDEF, +XSRETURN_YES, XST_mIV, XST_mNV, XST_mNO, XST_mPV, XST_mUNDEF, XST_mYES, +XS_VERSION, XS_VERSION_BOOTCHECK, Zero =item EDITOR diff --git a/pod/pod2man.PL b/pod/pod2man.PL index 934d525cd8..d1ba2287cd 100644 --- a/pod/pod2man.PL +++ b/pod/pod2man.PL @@ -46,6 +46,7 @@ B<pod2man> [ B<--date=>I<string> ] [ B<--fixed=>I<font> ] [ B<--official> ] +[ B<--lax> ] I<inputfile> =head1 DESCRIPTION @@ -105,6 +106,10 @@ best if you put your Perl man pages in a separate tree, like F</usr/local/perl/man/>. By default, section 1 will be used unless the file ends in F<.pm> in which case section 3 will be selected. +=item lax + +Don't complain when required sections aren't present. + =back =head1 Anatomy of a Proper Man Page @@ -329,6 +334,7 @@ $DEF_SECTION = 1; $DEF_CENTER = "User Contributed Perl Documentation"; $STD_CENTER = "Perl Programmers Reference Guide"; $DEF_FIXED = 'CW'; +$DEF_LAX = 0; sub usage { warn "$0: @_\n" if @_; @@ -341,6 +347,7 @@ Options are: --date=string (default "$DEF_DATE") --fixed=font (default "$DEF_FIXED") --official (default NOT) + --lax (default NOT) EOF } @@ -351,6 +358,7 @@ $uok = GetOptions( qw( date=s fixed=s official + lax help)); $DEF_DATE = makedate((stat($ARGV[0]))[9] || time()); @@ -362,6 +370,7 @@ usage("Need one and only one podpage argument") unless @ARGV == 1; $section = $opt_section || ($ARGV[0] =~ /\.pm$/ ? 3 : $DEF_SECTION); $RP = $opt_release || $DEF_RELEASE; $center = $opt_center || ($opt_official ? $STD_CENTER : $DEF_CENTER); +$lax = $opt_lax || $DEF_LAX; $CFont = $opt_fixed || $DEF_FIXED; @@ -410,9 +419,9 @@ if ($name ne 'something') { last FCHECK; } next if /^=cut\b/; # DB_File and Net::Ping have =cut before NAME - die "$0: Invalid man page - 1st pod line is not NAME in $ARGV[0]\n"; + die "$0: Invalid man page - 1st pod line is not NAME in $ARGV[0]\n" unless $lax; } - die "$0: Invalid man page - no documentation in $ARGV[0]\n"; + die "$0: Invalid man page - no documentation in $ARGV[0]\n" unless $lax; } close F; } @@ -861,7 +870,7 @@ print <<"END"; .rn }` '' END -if (%wanna_see) { +if (%wanna_see && !$lax) { @missing = keys %wanna_see; warn "$0: $Filename is missing required section" . (@missing > 1 && "s") @@ -945,13 +954,7 @@ sub escapes { # make troff just be normal, but make small nroff get quoted # decided to just put the quotes in the text; sigh; sub ccvt { - local($_,$prev) = @_; - if ( /^\W+$/ && !/^\$./ ) { - ($prev && "\n") . noremap(qq{.CQ $_ \n\\&}); - # what about $" ? - } else { - noremap(qq{${CFont_embed}$_\\fR}); - } + local($_,$prev) = @_; noremap(qq{.CQ "$_" \n\\&}); } |