[win32] merge changes#872,873 from maintbranch

p4raw-link: @873 on //depot/maint-5.004/perl: 990f469d529b62458be38e8659885fd26d353629
p4raw-link: @872 on //depot/maint-5.004/perl: 0b85608df162729d39cb0f96c9f88c7de0a3ceab

p4raw-id: //depot/win32/perl@935

diff --git a/Changes5.004 b/Changes5.004
index 90a8b53..da2166d 100644 (file)
--- a/Changes5.004
+++ b/Changes5.004
@@ -51,6 +51,853 @@ And, of course, the Author of Perl:
     Larry Wall          <larry@wall.org>
 
 ----------------
+Version 5.004_05        Maintenance release 5 for 5.004
+----------------
+
+"I said to my soul, be still, and wait without hope
+ For hope would hope for the wrong thing; wait without love
+ For love would be love of the wrong thing; there is yet faith
+ But the faith and the love and the hope are all in the waiting.
+ Wait without thought, for you are not ready for thought:
+ So the darkness shall be light, and the stillness the dancing."
+  -- T.S.Eliot, East Coker
+
+
+  HEADLINES FOR THIS MAINTENANCE RELEASE
+
+    TBA
+
+
+Change 764 on 1998/03/05 by TimBunce@ig.co.uk
+
+    APPLLIB_EXP now has arch and version dirs added to @INC
+
+Change 761 on 1998/03/05 by TimBunce@ig.co.uk
+
+     Title:  "properly refcount localization, fix C<local $tied{foo}>"
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199802191207.MAA10742@toad.ig.co.uk>
+     Files:  av.c hv.c scope.c t/op/local.t
+
+Change 758 on 1998/03/04 by TimBunce@ig.co.uk
+
+    perldoc -f now uses pager if text is too long for screen
+
+Change 757 on 1998/03/04 by TimBunce@ig.co.uk
+
+    Added OpenBSD hint file from <Todd.Miller@courtesan.com>
+    Document 'warn with no args' behaviour, from <johnpc@xs4all.net>
+
+Change 756 on 1998/03/04 by TimBunce@ig.co.uk
+
+    Fix for new gnulibc stdio.h when using sfio+perlio
+
+Change 755 on 1998/03/04 by TimBunce@ig.co.uk
+
+    Fixed typo in vms/ext/Stdio/Stdio.pm AUTOLOAD
+    Added details of split in scalar context to perlfunc.pod
+
+Change 754 on 1998/03/04 by TimBunce@ig.co.uk
+
+    Updated perl -v info to include reference to docs and home page.
+
+Change 753 on 1998/03/04 by TimBunce@ig.co.uk
+
+    Updated hints/bsdos.sh for BSD/OS 3.1
+    Fixed typo in pod/perlsyn.pod
+    Added workaround for old gmake in ext/SDBM_File/sdbm/Makefile.PL
+    Fixed typo in ext/GDBM_File/GDBM_File.pm
+
+Change 752 on 1998/03/04 by TimBunce@ig.co.uk
+
+    Changed bug address in README to perlbug@perl.com
+    Changed Copyright in perl.c to 1998
+    Added op/pos.t test from Robin Houston <robin@oneworld.org>
+
+Change 751 on 1998/03/04 by TimBunce@ig.co.uk
+
+    Make t/comp/require.t and t/lib/ph.t executable in repository
+
+Change 750 on 1998/03/04 by TimBunce@ig.co.uk
+
+    Added dTHR definition to ease backwards compatibility for XS
+       source code from 5.005.
+
+Change 749 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "rename local 'op' variables to 'o'", #F114
+      From:  Gurusamy Sarathy
+     Files:  op.h opcode.h proto.h dump.c op.c opcode.pl pp_ctl.c run.c scope.c
+             toke.c
+
+Change 748 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "consolidated win32 patch", #F112
+      From:  Gurusamy Sarathy
+     Files:  MANIFEST pod/perlfaq2.pod pod/perlrun.pod win32/include/sys/socket.h
+             EXTERN.h INTERN.h dosish.h lib/ExtUtils/Command.pm
+             lib/ExtUtils/Liblist.pm lib/ExtUtils/MM_Win32.pm
+             lib/ExtUtils/Mksymlists.pm lib/File/DosGlob.pm t/TEST
+             t/harness win32/win32.h win32/win32iop.h README.win32
+             doio.c installhtml installperl pp_sys.c win32/Makefile
+             win32/config.bc win32/config.vc win32/config_H.bc
+             win32/config_H.vc win32/config_h.PL win32/config_sh.PL
+             win32/dl_win32.xs win32/makedef.pl win32/makefile.mk
+             win32/perllib.c win32/runperl.c win32/win32.c
+             win32/win32sck.c win32/bin/perlglob.pl x2p/a2p.h x2p/a2p.c
+             x2p/a2py.c
+
+Change 747 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "initialize @INC in ph.t, and fix up MANIFEST", #F111
+      From:  Gurusamy Sarathy
+     Files:  MANIFEST t/lib/ph.t
+
+Change 746 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "properly save STDOUT during system() in debugger", #F110
+      From:  Jason Smith <smithj4@rpi.edu>
+     Files:  lib/perl5db.pl
+
+Change 745 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "generate DynaLoader.pm at build time", #F109
+      From:  Achim Bohnet <ach@mpe.mpg.de>
+    Msg-ID:  <9802111938.AA26224@o09.xray.mpe.mpg.de>
+     Files:  MANIFEST ext/DynaLoader/DynaLoader.pm.PL ext/DynaLoader/Makefile.PL
+
+Change 744 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "Install extensions with bootstrap in $archlib", #F108
+      From:  koenig@anna.mind.de (Andreas J. Koenig), koenig@kulturbox.de (Andreas
+             J. Koenig)
+    Msg-ID:  <sfcra9fqx0n.fsf@anna.in-berlin.de>
+     Files:  lib/ExtUtils/Install.pm
+
+Change 743 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "Pod::Html trips over "C<0>"", #F107
+      From:  Chip Salzenberg
+     Files:  lib/Pod/Html.pm
+
+Change 742 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "5.004_58 | _04: pod2*,perlpod: L<show this|man/section>", #F106
+      From:  Achim Bohnet <ach@mpe.mpg.de>
+    Msg-ID:  <9802111629.AA00595@o09.xray.mpe.mpg.de>
+     Files:  pod/perlpod.pod lib/Pod/Html.pm lib/Pod/Text.pm pod/pod2man.PL
+
+Change 741 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "New patch for $^E==GetLastError() under Win32", #F105
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>, Tye McQueen
+             <tye@metronet.com>, ilya@math.ohio-state.edu (Ilya
+             Zakharevich)
+    Msg-ID:  <199801040630.AA29298@metronet.com>,
+             <199801041826.NAA11568@aatma.engin.umich.edu>,
+             <1998Jan4.130412.2719461@cor.newman>
+     Files:  pod/perlfunc.pod pod/perlvar.pod doio.c lib/dumpvar.pl lib/perl5db.pl
+             win32/win32.h mg.c util.c win32/makedef.pl win32/win32.c
+
+Change 740 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "5.004_56: Patch to Tie::Hash and docs", #F104
+      From:  Ilya Zakharevich <ilya@math.ohio-state.edu>
+    Msg-ID:  <199801120134.UAA05437@monk.mps.ohio-state.edu>
+     Files:  pod/perlfunc.pod lib/Tie/Hash.pm
+
+Change 739 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "more doc for perldoc", #F103
+      From:  Gurusamy Sarathy
+     Files:  utils/perldoc.PL
+
+Change 738 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "Make perldoc look for an index file ", #F102
+      From:  Gisle Aas <gisle@aas.no>
+    Msg-ID:  <199801221220.NAA22902@furu.g.aas.no>
+     Files:  utils/perldoc.PL
+
+Change 737 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "perldoc -F filename", #F101
+      From:  Ilya Zakharevich <ilya@math.ohio-state.edu>
+    Msg-ID:  <199712120037.TAA00176@math.mps.ohio-state.edu>
+     Files:  utils/perldoc.PL
+
+Change 736 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "sv_grow can fail for HAS_64K_LIMIT systems", #F100
+      From:  Gisle Aas <gisle@aas.no>
+    Msg-ID:  <m3iuqsl3oq.fsf@furu.g.aas.no>
+     Files:  sv.c
+
+Change 735 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "Benchmark.pm: timethese corrupts $_", #F099
+      From:  abigail@fnx.com
+    Msg-ID:  <19980201114609.7779.qmail@betelgeuse.wayne.fnx.com>
+     Files:  lib/Benchmark.pm
+
+Change 734 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "STRANGE_MALLOC should test failed alloc", #F098
+      From:  Gisle Aas <gisle@aas.no>
+    Msg-ID:  <199802021406.PAA03285@furu.g.aas.no>
+     Files:  hv.c
+
+Change 733 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "support caseless %ENV", #F097
+      From:  Gurusamy Sarathy
+     Files:  hv.c t/op/magic.t win32/win32.h
+
+Change 732 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "newer cperl-mode.el (from 5.004_60)", #F096
+      From:  Ilya Zakharevich
+     Files:  emacs/cperl-mode.el
+
+Change 731 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "Handle set magic on xsub OUTPUT args, add API functions that handle
+             magic", #F095
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199801190409.XAA26710@aatma.engin.umich.edu>
+     Files:  pod/perlguts.pod pod/perlxs.pod embed.h proto.h sv.h global.sym
+             lib/ExtUtils/xsubpp sv.c
+
+Change 730 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "Fix flawed cleanup when signal handlers are not defined", #F094
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199710290106.UAA11485@aatma.engin.umich.edu>
+     Files:  mg.c
+
+Change 729 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "Tests for C<sort 'foo','bar'>", #F093
+      From:  Hugo van der Sanden <hv@crypt.compulink.co.uk>
+    Msg-ID:  <199711021247.MAA01743@crypt.compulink.co.uk>
+     Files:  t/op/sort.t
+
+Change 728 on 1998/03/04 by TimBunce@ig.co.uk
+
+     Title:  "Make search.pl work on win32", #F092
+      From:  Gurusamy Sarathy
+     Files:  win32/bin/search.pl
+
+Change 721 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix spurious perldoc warnings on DOSISH platforms", #F091
+      From:  Molnar Laszlo <molnarl@cdata.tvnet.hu>
+    Msg-ID:  <34475659.1AA69855@cdata.tvnet.hu>
+     Files:  utils/perldoc.PL
+
+Change 720 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Make ExtUtils::MM_Unix::fixin() do something meaningful on win32",
+             #F090
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199801070016.TAA17766@aatma.engin.umich.edu>
+     Files:  lib/ExtUtils/MM_Unix.pm
+
+Change 719 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix inconsistent case $ENV{Path} (vs $ENV{PATH})", #F089
+      From:  Gurusamy Sarathy
+     Files:  lib/FindBin.pm
+
+Change 718 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix File::Find's longstanding confusion about win32 being like VMS",
+             #F088
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199802020459.XAA04964@aatma.engin.umich.edu>
+     Files:  lib/File/Find.pm
+
+Change 717 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "do_postponed breaks with multiple interpreters", #F087
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199710290316.WAA15888@aatma.engin.umich.edu>
+     Files:  op.c
+
+Change 716 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Make warning on C<Nosuch::> optional, add to perl{diag,delta}.pod",
+             #F086
+      From:  Gurusamy Sarathy
+     Files:  pod/perldelta.pod pod/perldiag.pod toke.c
+
+Change 715 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Pod::Html bug and fix: missing </UL> in index", #F085
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199802192314.SAA23326@aatma.engin.umich.edu>
+     Files:  lib/Pod/Html.pm
+
+Change 714 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "New pod: perlhist", #F084
+      From:  Jarkko Hietaniemi <jhi@iki.fi>
+    Msg-ID:  <199802191556.RAA09578@alpha.hut.fi>
+     Files:  MANIFEST pod/perl.pod pod/perlhist.pod pod/perltoc.pod pod/buildtoc
+
+Change 713 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix restoration of locals on scope unwinding", #F083
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199802110515.AAA23700@aatma.engin.umich.edu>
+     Files:  pp_ctl.c t/op/local.t
+
+Change 712 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "after an eval-ed bad require, requiring a string ref SEGVs", #F082
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199802102349.SAA16001@aatma.engin.umich.edu>
+     Files:  pp_ctl.c
+
+Change 711 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix seg fault on eval/require and syntax errors", #F081
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199802102321.SAA15346@aatma.engin.umich.edu>
+     Files:  MANIFEST scope.h op.c pp_ctl.c scope.c t/comp/require.t toke.c
+
+Change 710 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "5.004_58: the locale.t problem in IRIX", #F080
+      From:  Jarkko Hietaniemi <jhi@iki.fi>
+    Msg-ID:  <199802091747.TAA01735@alpha.hut.fi>
+     Files:  t/pragma/locale.t
+
+Change 709 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "sv_setnv will upgrade SVt_NV to SVt_PVNV", #F079
+      From:  Gisle Aas <gisle@aas.no>
+    Msg-ID:  <m3g1lwl3bq.fsf@furu.g.aas.no>
+     Files:  sv.c
+
+Change 708 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Eliminate double warnings under C<package;>", #F077
+      From:  "M.J.T. Guy" <mjtg@cus.cam.ac.uk>
+    Msg-ID:  <E0y0paq-0000Ov-00@ursa.cus.cam.ac.uk>
+     Files:  gv.c op.c toke.c
+
+Change 707 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix infinite loop on unlink() failure in File::Path::rmtree()",
+             #F076
+      From:  Murray Nesbitt <mjn@pathcom.com>, Tim Bunce <Tim.Bunce@ig.co.uk>
+    Msg-ID:  <199802061100.LAA16423@toad.ig.co.uk>
+     Files:  lib/File/Path.pm
+
+Change 706 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Update of h2ph", #F075
+      From:  kstar@www.chapin.edu (Kurt D. Starsinic)
+    Msg-ID:  <199802051354.FAA11452@www.chapin.edu>
+     Files:  t/lib/ph.t utils/h2ph.PL
+
+Change 705 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix AutoLoader for deep packages", #F074
+      From:  Zachary Miller <zcmiller@zappy.er.usgs.gov>
+    Msg-ID:  <199710092348.SAA02108@zappy.er.usgs.gov>
+     Files:  lib/AutoLoader.pm
+
+Change 704 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix order of warnings for misplaced subscripts", #F073
+      From:  Hugo van der Sanden <hv@crypt.compulink.co.uk>
+    Msg-ID:  <199710131023.LAA16796@crypt.compulink.co.uk>
+     Files:  op.c
+
+Change 703 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Make recursive lexical analysis more robust", #F072
+      From:  Ilya Zakharevich and Chip Salzenberg
+    Msg-ID:  <199710160102.VAA28817@monk.mps.ohio-state.edu>
+     Files:  toke.c
+
+Change 702 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix random whitespace errors in docs", #F070
+      From:  Roderick Schertler <roderick@argon.org>
+    Msg-ID:  <12726.877706444@eeyore.ibcinc.com>
+     Files:  pod/perlfunc.pod pod/checkpods.PL
+
+Change 701 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix line numbers after here documents in eval STRING", #F069
+      From:  Ilya Zakharevich <ilya@math.ohio-state.edu>
+    Msg-ID:  <199710241745.NAA08166@monk.mps.ohio-state.edu>
+     Files:  toke.c
+
+Change 700 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix SEGV from combining caller and C<package;>", #F068
+      From:  James Duncan <jduncan@epitome.hawk.igs.net>, Nicholas Clark
+             <nick@flirble.org>
+    Msg-ID:  <199710241248.NAA00163@flirble.org>,
+             <Pine.LNX.3.96.971024135912.12197A-100000@epitome.hawk.igs.
+             net>
+     Files:  pp_ctl.c sv.c
+
+Change 699 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Don't fold string comparison under C<use locale>", #F067
+      From:  Jarkko Hietaniemi <jhi@iki.fi>
+    Msg-ID:  <199711151506.RAA26287@alpha.hut.fi>
+     Files:  op.c
+
+Change 698 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix SEGV on constant at end of sort block", #F066
+      From:  Administration <fadmin@informatics.muni.cz>
+    Msg-ID:  <199711170838.JAA26073@thetis.fi.muni.cz>
+     Files:  op.c
+
+Change 697 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Allow C<last()> to mean C<last>", #F065
+      From:  Chip Salzenberg
+     Files:  op.c
+
+Change 696 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix extension version mismatch message", #F064
+      From:  Chip Salzenberg
+     Files:  XSUB.h
+
+Change 695 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Better handle and test struct tm of Linux and SunOS", #F063
+      From:  Andy Dougherty <doughera@newton.phys.lafayette.edu>
+    Msg-ID:  <Pine.SUN.3.96.980205134340.15567B-100000@newton.phys>
+     Files:  MANIFEST ext/POSIX/hints/linux.pl ext/POSIX/hints/sunos_4.pl
+             hints/linux.sh hints/sunos_4_1.sh t/lib/posix.t
+
+Change 694 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix doc bug in getservbyname() examples", #F062
+      From:  Tom Christiansen
+     Files:  ext/Socket/Socket.pm
+
+Change 693 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Kill warning about parameter type", #F061
+      From:  Chip Salzenberg
+     Files:  op.c
+
+Change 692 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Socket occasional SEGV", #F060
+      From:  Trevor Blackwell <tlb@viaweb.com>
+    Msg-ID:  <199710281804.NAA09632@wagg.viaweb.com>
+     Files:  ext/Socket/Socket.xs
+
+Change 691 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Avoid SEGV from local($@)", #F059
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199710290251.VAA14362@aatma.engin.umich.edu>
+     Files:  pp_ctl.c
+
+Change 690 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Don't use broken pad_reset() (was Re: Perl bug in 5.004_03 )", #F058
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199710300036.TAA01004@aatma.engin.umich.edu>
+     Files:  op.c
+
+Change 689 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Use STMT_{START,END} in XSRETURN", #F057
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199710300245.VAA04244@aatma.engin.umich.edu>
+     Files:  XSUB.h
+
+Change 688 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Re: Sort grammar bug", #F056
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199711011946.OAA18882@aatma.engin.umich.edu>
+     Files:  toke.c
+
+Change 687 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Document indirect object cases for exec(), system()", #F055
+      From:  Dominic Dunlop <domo@slipper.ip.lu>
+    Msg-ID:  <v03110700b084e89234a7@[194.51.248.90]>
+     Files:  pod/perlfunc.pod
+
+Change 686 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Update docs on tr///", #F054
+      From:  Tom Phoenix <rootbeer@teleport.com>
+    Msg-ID:  <Pine.GSO.3.96.971103071602.10568C-100000@usertest.teleport.com>
+     Files:  pod/perldelta.pod pod/perldiag.pod pod/perlfunc.pod
+             pod/perllocale.pod pod/perlmod.pod pod/perlop.pod
+             pod/perlstyle.pod toke.c
+
+Change 685 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Re: perlop bitwise & | ^ documentation", #F053
+      From:  Tom Phoenix <rootbeer@teleport.com>
+    Msg-ID:  <Pine.GSO.3.96.971106073858.29771O-100000@usertest.teleport.com>
+     Files:  pod/perlop.pod
+
+Change 684 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix SEGV on C<*glob{'SCALAR','ARRAY'}>", #F052
+      From:  "Joseph N. Hall" <joseph@cscaper.com>
+    Msg-ID:  <199711110552.WAA12613@gadget.cscaper.com>
+     Files:  perly.c perly.c.diff perly.y vms/perly_c.vms
+
+Change 683 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "for perlguts.pod: document sv_derived_from, sv_vcatpfn and
+             sv_vsetpfn", #F051
+      From:  jan.dubois@ibm.net (Jan Dubois) and Chip Salzenberg
+    Msg-ID:  <346ae970.7444534@smtp1.ibm.net>
+     Files:  pod/perlguts.pod
+
+Change 682 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "5.004_04: locale startup failure (at last) documented", #F050
+      From:  Jarkko Hietaniemi <jhi@iki.fi>
+    Msg-ID:  <199711172054.WAA08261@alpha.hut.fi>
+     Files:  INSTALL pod/perldiag.pod pod/perllocale.pod
+
+Change 681 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Cope with lack of args in Fcntl::AUTOLOAD", #F049
+      From:  Jerome Abela <abela@hsc.fr>
+    Msg-ID:  <19971120183248.23588@coredump.hsc.fr>
+     Files:  ext/Fcntl/Fcntl.pm
+
+Change 680 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Commenting toke.c", #F048
+      From:  gnat@frii.com
+    Msg-ID:  <199801082138.OAA14186@prometheus.frii.com>
+     Files:  toke.c
+
+Change 679 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Re: 5.004_04 vec() fails with 32-bit values", #F047
+      From:  "M.J.T. Guy" <mjtg@cus.cam.ac.uk>
+    Msg-ID:  <E0xsnr8-0007SS-00@taurus.cus.cam.ac.uk>
+     Files:  pod/perlguts.pod pp.c t/op/vec.t
+
+Change 678 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "A few perl5.004_03 bugs", #F046
+      From:  Hugo van der Sanden <hv@crypt.compulink.co.uk>
+    Msg-ID:  <199801221211.MAA05315@crypt.compulink.co.uk>
+     Files:  mg.c t/op/magic.t
+
+Change 677 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Faster, cleaner av_unshift() ", #F045
+      From:  Gisle Aas <gisle@aas.no>
+    Msg-ID:  <199801221850.TAA23111@furu.g.aas.no>
+     Files:  av.c
+
+Change 676 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "New hints/solaris2.sh", #F044
+      From:  Stephen Zander <srz@mckesson.com>
+    Msg-ID:  <87oh12y458.fsf@wsuse5.mckesson.com>
+     Files:  hints/solaris_2.sh
+
+Change 675 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Refresh Complex.pm and test", #F043
+      From:  Jarkko Hietaniemi <jhi@iki.fi>
+    Msg-ID:  <199802051608.SAA20262@alpha.hut.fi>
+     Files:  lib/Math/Complex.pm t/lib/complex.t
+
+Change 674 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix (\@@) proto", #F042
+      From:  "Joseph N. Hall" <joseph@cscaper.com>
+    Msg-ID:  <199801240132.SAA25111@gadget.cscaper.com>
+     Files:  op.c t/comp/proto.t
+
+Change 673 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Allow empty BLOCK in code", #F041
+      From:  Vladimir Alexiev <vladimir@cs.ualberta.ca>
+    Msg-ID:  <19980129002112Z13378-6931+226@scapa.cs.ualberta.ca>
+     Files:  toke.c
+
+Change 672 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix name of $Foo::{'Bar::'}: '*Foo::Bar::'", #F040
+      From:  Chip Salzenberg
+     Files:  gv.c t/op/gv.t
+
+Change 671 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Keep accurate reference count on globs' stashes", #F038
+      From:  Gisle Aas <gisle@aas.no>
+    Msg-ID:  <m3zpk7sd3n.fsf@furu.g.aas.no>
+     Files:  gv.c sv.c
+
+Change 670 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Avoid memory allocation in gv_fetchpv(), for speed", #F037
+      From:  Chip Salzenberg
+     Files:  gv.c
+
+Change 669 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Make Configure less negative about PerlIO", #F036
+      From:  chip@atlantic.net
+    Msg-ID:  <199801312323.SAA15237@cyprus.atlantic.net>
+     Files:  Configure
+
+Change 668 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix (mostly) pseudo-same-REs due to embedded NULs", #F035
+      From:  Martin Plechsmid <plechsmi@karlin.mff.cuni.cz>
+    Msg-ID:  <199802021217.NAA05230@albert.karlin.mff.cuni.cz>
+     Files:  pp_ctl.c
+
+Change 667 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Make Getopt::Long avoid $&, $`, $'", #F034
+      From:  Irving Reid <irving@tor.securecomputing.com>
+    Msg-ID:  <98Feb3.005102est.11655@janus.tor.securecomputing.com>
+     Files:  lib/Getopt/Long.pm
+
+Change 666 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "adding the newSVpvn API function", #F033
+      From:  Matthias Ulrich Neeracher <neeri@iis.ee.ethz.ch>
+    Msg-ID:  <199801310532.GAA23798@solar.ethz.ch>
+     Files:  pod/perlguts.pod pod/perltoc.pod proto.h global.sym sv.c
+
+Change 665 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Support C<Package::> as function-blind bearword", #F032
+      From:  Chip Salzenberg
+     Files:  toke.c
+
+Change 664 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Re-optimize character classes", #F031
+      From:  Chip Salzenberg
+     Files:  regcomp.h regcomp.c regexec.c
+
+Change 663 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix C<if (1) { local $x }> which needed ENTER/LEAVE", #F030
+      From:  dfh@dwroll.lucent.com (D461-David_F_Haertig(Dave)83040)
+    Msg-ID:  <EnKC0q.6qI@drnews.dr.lucent.com>
+     Files:  op.c t/op/local.t
+
+Change 662 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Dramatically improve performance of // with parens or $&", #F029
+      From:  Chip Salzenberg
+     Files:  cop.h perl.h proto.h regexp.h gv.c interp.sym perl.c pp.c pp_ctl.c
+             pp_hot.c regexec.c scope.c
+
+Change 661 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Don't warn on $x{shift}, ne => 1, or -f => 1", #F028
+      From:  Chip Salzenberg
+     Files:  toke.c
+
+Change 660 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Protect against weirdness with unreal @_ in C<local @_>", #F027
+      From:  Chip Salzenberg
+     Files:  scope.c
+
+Change 659 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix C<printf "%.0d", 0>", #F026
+      From:  Hugo van der Sanden <hv@crypt.compulink.co.uk>
+    Msg-ID:  <199711021331.NAA01826@crypt.compulink.co.uk>
+     Files:  sv.c t/op/sprintf.t
+
+Change 658 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Tiny core patch for source filters", #F025
+      From:  pmarquess@bfsec.bt.co.uk (Paul Marquess)
+    Msg-ID:  <9711202312.AA02937@claudius.bfsec.bt.co.uk>
+     Files:  toke.c
+
+Change 657 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Here-doc in s///e (was: Bug)", #F024
+      From:  Hugo van der Sanden <hv@crypt.compulink.co.uk>
+    Msg-ID:  <199711221445.OAA14153@crypt.compulink.co.uk>
+     Files:  t/base/lex.t toke.c
+
+Change 656 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix duplicate warnings on C<-e undef>", #F023
+      From:  Hugo van der Sanden <hv@crypt.compulink.co.uk>
+    Msg-ID:  <199711221252.MAA14000@crypt.compulink.co.uk>
+     Files:  doio.c t/pragma/warn-1global
+
+Change 655 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix '*' prototype", #F022
+      From:  Ilya Zakharevich <ilya@math.ohio-state.edu>
+    Msg-ID:  <199711212225.RAA00755@monk.mps.ohio-state.edu>
+     Files:  toke.c
+
+Change 654 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "File::Find bugs (and patches)", "File::Find bugs & patches", #F021
+      From:  "Conrad E. Kimball" <cek@tblv021.ca.boeing.com>
+    Msg-ID:  <199711260703.XAA21257@mailgate2.boeing.com>
+     Files:  lib/File/Find.pm
+
+Change 653 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix typo: FORM{,AT}LINE", #F020
+      From:  Chip Salzenberg
+     Files:  sv.c
+
+Change 652 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix use of unref mem when blessed object goes out of scope", #F019
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199711282326.SAA15090@aatma.engin.umich.edu>
+     Files:  scope.c
+
+Change 651 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix C<my ($a, undef, $b) = @x>", #F018
+      From:  Stephane Payrard <stef@francenet.fr>
+    Msg-ID:  <199712040054.BAA04612@www.zweig.com>
+     Files:  op.c t/op/my.t
+
+Change 650 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "enhanced "use strict" warning", #F017
+      From:  Tkil <tkil@reptile.scrye.com>
+    Msg-ID:  <199712040938.CAA07628@reptile.scrye.com>
+     Files:  gv.c t/pragma/strict-subs t/pragma/strict-vars
+
+Change 649 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "eval of sub gives spurious "uninitialised" warning", #F016
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199712061025.FAA14396@aatma.engin.umich.edu>
+     Files:  pod/perldelta.pod pod/perlfunc.pod op.c t/op/eval.t
+
+Change 648 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "[PERL] Assigning result of pop scrambles unrelated reference", #F015
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199712061100.GAA14864@aatma.engin.umich.edu>
+     Files:  sv.c
+
+Change 647 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "[PERL] Filedescriptor leak in 5.004_55 (and earlier)", #F014
+      From:  Ilya Zakharevich <ilya@math.ohio-state.edu>
+    Msg-ID:  <199712151922.OAA06410@monk.mps.ohio-state.edu>
+     Files:  os2/os2.c util.c
+
+Change 646 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix fdopen() on STD{IN,OUT,ERR}", #F013
+      From:  Roderick Schertler <roderick@argon.org>
+    Msg-ID:  <pzg1npp6e3.fsf@eeyore.ibcinc.com>
+     Files:  doio.c t/op/misc.t
+
+Change 645 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix local $a[0] and local $h{a}", #F012
+      From:  Stephen McCamant <alias@mcs.com>
+    Msg-ID:  <m0xjWFq-000EZeC@alias-2.pr.mcs.net>
+     Files:  embed.h scope.h global.sym pp.c pp_hot.c scope.c t/op/local.t
+
+Change 644 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Eliminate redundant mg_get() in SvTRUE()", #F011
+      From:  Spider Boardman <spider@orb.nashua.nh.us>
+    Msg-ID:  <199712251839.NAA14800@Orb.Nashua.NH.US>
+     Files:  sv.c
+
+Change 643 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Don't force scalar context on C<my @x> or C<my %x>", #F010
+      From:  Chip Salzenberg
+     Files:  op.c t/op/my.t
+
+Change 642 on 1998/03/03 by TimBunce@ig.co.uk
+
+     Title:  "Fix assignment to $_[0] in DESTROY", #F009
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199801010030.TAA14274@aatma.engin.umich.edu>
+     Files:  pod/perlobj.pod sv.c t/op/ref.t
+
+Change 627 on 1998/03/02 by TimBunce@ig.co.uk
+
+     Title:  "Fix inefficient checks for TIEHANDLE", #F008
+      From:  Gurusamy Sarathy <gsar@engin.umich.edu>
+    Msg-ID:  <199801080106.UAA05048@aatma.engin.umich.edu>
+     Files:  pp_hot.c pp_sys.c
+
+Change 626 on 1998/03/02 by TimBunce@ig.co.uk
+
+             This is the change description for change 625
+     Title:  "Fix tr///s option", #F007
+      From:  Inaba Hiroto <inaba@st.rim.or.jp>
+    Msg-ID:  <19980110155333D.inaba@st.rim.or.jp>
+     Files:  doop.c
+
+Change 625 on 1998/03/02 by TimBunce@ig.co.uk
+
+
+Change 624 on 1998/03/02 by TimBunce@ig.co.uk *pending*
+
+
+Change 623 on 1998/03/02 by TimBunce@ig.co.uk
+
+     Title:  "Fix lexical lookup in eval-sub-eval", #F006
+      From:  Chip Salzenberg
+     Files:  pp_ctl.c
+
+Change 622 on 1998/03/02 by TimBunce@ig.co.uk
+
+     Title:  "Don't upgrade target of assignment from LVALUE", #F005
+      From:  Chip Salzenberg
+     Files:  sv.c
+
+Change 621 on 1998/03/02 by TimBunce@ig.co.uk
+
+     Title:  "Fix compile-time warning line in while ()", #F004
+      From:  Chip Salzenberg
+     Files:  op.c
+
+Change 620 on 1998/03/02 by TimBunce@ig.co.uk
+
+     Title:  "STMT foreach LIST;", #F002
+      From:  Chip Salzenberg
+     Files:  pod/perlsyn.pod perly.c perly.c.diff perly.y t/cmd/mod.t toke.c
+             vms/perly_c.vms
+
+Change 619 on 1998/03/02 by TimBunce@ig.co.uk
+
+     Title:  "Fix SIGSEGV on C<42 until forever>", #F001
+      From:  Chip Salzenberg
+     Files:  op.c
+
+----------------
 Version 5.004_04        Maintenance release 4 for 5.004
 ----------------
 

diff --git a/INSTALL b/INSTALL
index 2454fd7..f99be4d 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -125,7 +125,7 @@ L<"Site-wide Policy settings"> below.
 Configure will figure out various things about your system.  Some
 things Configure will figure out for itself, other things it will ask
 you about.  To accept the default, just press RETURN.   The default
-is almost always ok.  At any Configure prompt, you can type  &-d
+is almost always okay.  At any Configure prompt, you can type  &-d
 and Configure will use the defaults from then on.
 
 After it runs, Configure will perform variable substitution on all the
@@ -162,6 +162,14 @@ NOTE:  You must not specify an installation directory that is below
 your perl source directory.  If you do, installperl will attempt
 infinite recursion.
 
+It may seem obvious to say, but Perl is useful only when users can
+easily find it. When possible, it's good for both /usr/bin/perl and
+/usr/local/bin/perl to be symlinks to the actual binary. If that can't
+be done, system administrators are strongly encouraged to put
+(symlinks to) perl and its accompanying utilities, such as perldoc,
+into a directory typically found along a user's PATH, or in another
+obvious and convenient place.
+
 By default, Configure will compile perl to use dynamic loading if
 your system supports it.  If you want to force perl to be compiled
 statically, you can either choose this when Configure prompts you or
@@ -751,7 +759,7 @@ you probably want to do
 This will do two independent things:  First, it will force compilation
 to use cc -g so that you can use your system's debugger on the
 executable.  (Note:  Your system may actually require something like
-cc -g2.  Check you man pages for cc(1) and also any hint file for your
+cc -g2.  Check your man pages for cc(1) and also any hint file for your
 system.)  Second, it will add -DDEBUGGING to your ccflags variable in
 config.sh so that you can use B<perl -D> to access perl's internal
 state.  (Note: Configure will only add -DDEBUGGING by

diff --git a/lib/ExtUtils/MakeMaker.pm b/lib/ExtUtils/MakeMaker.pm
index f3b843f..ee451c7 100644 (file)
--- a/lib/ExtUtils/MakeMaker.pm
+++ b/lib/ExtUtils/MakeMaker.pm
@@ -1538,15 +1538,14 @@ Hashref of .pm files and *.pl files to be installed.  e.g.
 
   {'name_of_file.pm' => '$(INST_LIBDIR)/install_as.pm'}
 
-By default this will include *.pm and *.pl. If a lib directory
-exists and is not listed in DIR (above) then any *.pm and *.pl files
-it contains will also be included by default.  Defining PM in the
+By default this will include *.pm and *.pl and the files found in
+the PMLIBDIRS directories.  Defining PM in the
 Makefile.PL will override PMLIBDIRS.
 
 =item PMLIBDIRS
 
 Ref to array of subdirectories containing library files.  Defaults to
-[ 'lib', $(BASEEXT) ]. The directories will be scanned and any files
+[ 'lib', $(BASEEXT) ]. The directories will be scanned and I<any> files
 they contain will be installed in the corresponding location in the
 library.  A libscan() method can be used to alter the behaviour.
 Defining PM in the Makefile.PL will override PMLIBDIRS.

diff --git a/lib/FileHandle.pm b/lib/FileHandle.pm
index 455fc63..72ecdac 100644 (file)
--- a/lib/FileHandle.pm
+++ b/lib/FileHandle.pm
@@ -249,6 +249,10 @@ It will also croak() if accidentally called in a scalar context.
 
 =back
 
+There are many other functions available since FileHandle is descended
+from IO::File, IO::Seekable, and IO::Handle.  Please see those
+respective pages for documentation on more functions.
+
 =head1 SEE ALSO
 
 The B<IO> extension,

diff --git a/lib/Tie/Hash.pm b/lib/Tie/Hash.pm
index 89fd61d..7ed1896 100644 (file)
--- a/lib/Tie/Hash.pm
+++ b/lib/Tie/Hash.pm
@@ -67,7 +67,7 @@ Return the (key, value) pair for the first key in the hash.
 
 =item NEXTKEY this, lastkey
 
-Return the next (key, value) pair for the hash.
+Return the next key for the hash.
 
 =item EXISTS this, key
 

diff --git a/lib/constant.pm b/lib/constant.pm
index a0d4f9d..464e20c 100644 (file)
--- a/lib/constant.pm
+++ b/lib/constant.pm
@@ -106,6 +106,15 @@ name as a constant. This is probably a Good Thing.
 Unlike constants in some languages, these cannot be overridden
 on the command line or via environment variables.
 
+You can get into trouble if you use constants in a context which
+automatically quotes barewords (as is true for any subroutine call).
+For example, you can't say C<$hash{CONSTANT}> because C<CONSTANT> will
+be interpreted as a string.  Use C<$hash{CONSTANT()}> or
+C<$hash{+CONSTANT}> to prevent the bareword quoting mechanism from
+kicking in.  Similarly, since the C<=E<gt>> operator quotes a bareword
+immediately to its left you have to say C<CONSTANT() =E<gt> 'value'>
+instead of C<CONSTANT =E<gt> 'value'>.
+
 =head1 AUTHOR
 
 Tom Phoenix, E<lt>F<rootbeer@teleport.com>E<gt>, with help from

diff --git a/lib/integer.pm b/lib/integer.pm
index a88ce6a..8949318 100644 (file)
--- a/lib/integer.pm
+++ b/lib/integer.pm
@@ -12,11 +12,22 @@ integer - Perl pragma to compute arithmetic in integer instead of double
 
 =head1 DESCRIPTION
 
-This tells the compiler that it's okay to use integer operations
+This tells the compiler to use integer operations
 from here to the end of the enclosing BLOCK.  On many machines, 
 this doesn't matter a great deal for most computations, but on those 
 without floating point hardware, it can make a big difference.
 
+Note that this affects the operations, not the numbers.  If you run this
+code
+
+    use integer;
+    $x = 1.5;
+    $y = $x + 1;
+    $z = -1.5;
+
+you'll be left with C<$x == 1.5>, C<$y == 2> and C<$z == -1>.  The $z
+case happens because unary C<-> counts as an operation.
+
 See L<perlmod/Pragmatic Modules>.
 
 =cut

diff --git a/pod/perl.pod b/pod/perl.pod
index 41481a3..a7e02f6 100644 (file)
--- a/pod/perl.pod
+++ b/pod/perl.pod
@@ -21,6 +21,7 @@ of sections:
     perl       Perl overview (this section)
     perldelta  Perl changes since previous version
     perlfaq    Perl frequently asked questions
+    perltoc    Perl documentation table of contents
 
     perldata   Perl data structures
     perlsyn    Perl syntax

diff --git a/pod/perlbook.pod b/pod/perlbook.pod
index 9a725cb..f5bf99d 100644 (file)
--- a/pod/perlbook.pod
+++ b/pod/perlbook.pod
@@ -12,13 +12,14 @@ an online order form.
 
 I<Programming Perl, Second Edition> is a reference work that covers
 nearly all of Perl, while I<Learning Perl, Second Edition> is a
-tutorial that covers the most frequently used subset of the language.
-You might also check out the very handy, inexpensive, and compact
-I<Perl 5 Desktop Reference>, especially when the thought of lugging
-the 676-page Camel around doesn't make much sense.  I<Mastering
-Regular Expressions>, by Jeffrey Friedl, is a reference work that
-covers the art and implementation of regular expressions in various
-languages including Perl.
+tutorial that covers the most frequently used subset of the language,
+and I<Advanced Perl Programming> is an indepth study of complex topics
+including the internals of perl.  You might also check out the very 
+handy, inexpensive, and compact I<Perl 5 Desktop Reference>, especially
+when the thought of lugging the 676-page Camel around doesn't make much
+sense.  I<Mastering Regular Expressions>, by Jeffrey Friedl, is a 
+reference work that covers the art and implementation of regular
+expressions in various languages including Perl.
 
     Programming Perl, Second Edition (the Camel Book):
        ISBN 1-56592-149-6      (English)
@@ -26,6 +27,9 @@ languages including Perl.
     Learning Perl, Second Edition (the Llama Book):
        ISBN 1-56592-284-0      (English)
 
+    Advanced Perl Programming:
+       ISBN 1-56592-220-4      (English)
+
     Perl 5 Desktop Reference (the reference card):
        ISBN 1-56592-187-9      (brief English)
 

diff --git a/pod/perldsc.pod b/pod/perldsc.pod
index 48750dd..cd689e3 100644 (file)
--- a/pod/perldsc.pod
+++ b/pod/perldsc.pod
@@ -305,7 +305,7 @@ debugger includes several new features, including command line editing as
 well as the C<x> command to dump out complex data structures.  For
 example, given the assignment to $LoL above, here's the debugger output:
 
-    DB<1> X $LoL
+    DB<1> x $LoL
     $LoL = ARRAY(0x13b5a0)
        0  ARRAY(0x1f0a24)
          0  'fred'
@@ -324,8 +324,6 @@ example, given the assignment to $LoL above, here's the debugger output:
          2  'elroy'
          3  'judy'
 
-There's also a lowercase B<x> command which is nearly the same.
-
 =head1 CODE EXAMPLES
 
 Presented with little comment (these will get their own manpages someday)

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 9c021ce..8ed7079 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1186,6 +1186,12 @@ that doesn't implement flock(2), fcntl(2) locking, or lockf(3).  flock()
 is Perl's portable file locking interface, although it locks only entire
 files, not records.
 
+On many platforms (including most versions or clones of Unix), locks
+established by flock() are B<merely advisory>.  This means that files
+locked with flock() may be modified by programs which do not also use
+flock().  Windows NT and OS/2, however, are among the platforms which
+supply mandatory locking.  See your local documentation for details.
+
 OPERATION is one of LOCK_SH, LOCK_EX, or LOCK_UN, possibly combined with
 LOCK_NB.  These constants are traditionally valued 1, 2, 8 and 4, but
 you can use the symbolic names if import them from the Fcntl module,
@@ -1815,10 +1821,18 @@ In a scalar context, returns the ctime(3) value:
 
     $now_string = localtime;  # e.g., "Thu Oct 13 04:54:34 1994"
 
-This scalar value is B<not> locale dependent, see L<perllocale>,
-but instead a Perl builtin.
-Also see the Time::Local module, and the strftime(3) and mktime(3)
-function available via the POSIX module.
+This scalar value is B<not> locale dependent, see L<perllocale>, but
+instead a Perl builtin.  Also see the Time::Local module, and the
+strftime(3) and mktime(3) function available via the POSIX module.  To
+get somewhat similar but locale dependent date strings, set up your
+locale environment variables appropriately (please see L<perllocale>)
+and try for example
+
+       use POSIX qw(strftime)
+       $now_string = strftime "%a %b %e %H:%M:%S %Y", localtime;
+
+Note that the C<%a> and C<%b>, the short forms of the day of the week
+and the month of the year, may not necessarily be three characters wide.
 
 =item log EXPR
 
@@ -2363,7 +2377,8 @@ you will have to use a block returning its value instead:
 
 =item printf FORMAT, LIST
 
-Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>.  The first argument
+Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>, except that $\
+(the output record separator) is not appended.  The first argument
 of the list will be interpreted as the printf format.  If C<use locale> is
 in effect, the character used for the decimal point in formatted real numbers
 is affected by the LC_NUMERIC locale.  See L<perllocale>.
@@ -2494,7 +2509,7 @@ operator is discussed in more detail in L<perlop/"I/O Operators">.
 
 Receives a message on a socket.  Attempts to receive LENGTH bytes of
 data into variable SCALAR from the specified SOCKET filehandle.
-Actually does a C recvfrom(), so that it can returns the address of the
+Actually does a C recvfrom(), so that it can return the address of the
 sender.  Returns the undefined value if there's an error.  SCALAR will
 be grown or shrunk to the length actually read.  Takes the same flags
 as the system call of the same name.
@@ -3258,7 +3273,7 @@ and the conversion letter:
    +       prefix positive number with a plus sign
    -       left-justify within the field
    0       use zeros, not spaces, to right-justify
-   #       prefix octal with "0", hex with "0x"
+   #       prefix non-zero octal with "0", non-zero hex with "0x"
    number  minimum field width
    .number "precision": digits after decimal point for floating-point,
            max length for string, minimum length for integer
@@ -3484,13 +3499,17 @@ unimplemented, produces a fatal error.  The arguments are interpreted
 as follows: if a given argument is numeric, the argument is passed as
 an int.  If not, the pointer to the string value is passed.  You are
 responsible to make sure a string is pre-extended long enough to
-receive any result that might be written into a string.  If your
+receive any result that might be written into a string.  You can't use a
+string literal (or other read-only string) as an argument to syscall()
+because Perl has to assume that any string pointer might be written
+through.  If your
 integer arguments are not literals and have never been interpreted in a
 numeric context, you may need to add 0 to them to force them to look
 like numbers.
 
     require 'syscall.ph';              # may need to run h2ph
-    syscall(&SYS_write, fileno(STDOUT), "hi there\n", 9);
+    $s = "hi there\n";
+    syscall(&SYS_write, fileno(STDOUT), $s, length $s);
 
 Note that Perl supports passing of up to only 14 arguments to your system call,
 which in practice should usually suffice.
@@ -3739,7 +3758,8 @@ The transliteration operator.  Same as y///. See L<perlop>.
 
 Truncates the file opened on FILEHANDLE, or named by EXPR, to the
 specified length.  Produces a fatal error if truncate isn't implemented
-on your system.
+on your system.  Returns TRUE if successful, the undefined value
+otherwise.
 
 =item uc EXPR
 
@@ -3936,7 +3956,8 @@ Changes the access and modification times on each file of a list of
 files.  The first two elements of the list must be the NUMERICAL access
 and modification times, in that order.  Returns the number of files
 successfully changed.  The inode modification time of each file is set
-to the current time.  Example of a "touch" command:
+to the current time.  This code has the same effect as the "touch"
+command if the files already exist:
 
     #!/usr/bin/perl
     $now = time;

diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index b46ccc3..d51e52b 100644 (file)
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -76,8 +76,8 @@ the format.
 The C<sv_set*()> functions are not generic enough to operate on values
 that have "magic".  See L<Magic Virtual Tables> later in this document.
 
-All SVs that will contain strings should, but need not, be terminated
-with a NUL character.  If it is not NUL-terminated there is a risk of
+All SVs that contain strings should be terminated with a NUL character.
+If it is not NUL-terminated there is a risk of
 core dumps and corruptions from code which passes the string to C
 functions or system calls which expect a NUL-terminated string.
 Perl's own functions typically add a trailing NUL for this reason.
@@ -614,8 +614,7 @@ including (but not limited to) the following:
     Scalar Value
     Array Value
     Hash Value
-    File Handle
-    Directory Handle
+    I/O Handle
     Format
     Subroutine
 
@@ -1427,7 +1426,7 @@ created.
 =head2 Compile pass 2: context propagation
 
 When a context for a part of compile tree is known, it is propagated
-down through the tree.  Aat this time the context can have 5 values
+down through the tree.  At this time the context can have 5 values
 (instead of 2 for runtime context): void, boolean, scalar, list, and
 lvalue.  In contrast with the pass 1 this pass is processed from top
 to bottom: a node's context determines the context for its children.

diff --git a/pod/perlhist.pod b/pod/perlhist.pod
index 163fe03..cbbe0b9 100644 (file)
--- a/pod/perlhist.pod
+++ b/pod/perlhist.pod
@@ -6,7 +6,7 @@ perlhist - the Perl history records
 
 =for RCS
 #
-# $Id: perlhist.pod,v 1.29 1998/02/19 15:49:17 jhi Exp $
+# $Id: perlhist.pod,v 1.31 1998/03/10 16:39:28 jhi Exp $
 #
 =end RCS
 
@@ -18,8 +18,8 @@ This document aims to record the Perl source code releases.
 
 Perl history in brief, by Larry Wall:
 
-   Perl 0 introduced Perl to my officemates.
-   Perl 1 introduced Perl to the world, and changed /\(...\|...\)/ to
+    Perl 0 introduced Perl to my officemates.
+    Perl 1 introduced Perl to the world, and changed /\(...\|...\)/ to
         /(...|...)/.  \(Dan Faigin still hasn't forgiven me. :-\)
     Perl 2 introduced Henry Spencer's regular expression package.
     Perl 3 introduced the ability to handle binary data (embedded nulls).
@@ -30,8 +30,8 @@ Perl history in brief, by Larry Wall:
 
 =head1 THE KEEPERS OF THE PUMPKIN
 
-Larry Wall, Andy Dougherty, Tom Christiansen, Charles Bailey, Nick
-Ing-Simmons, Chip Salzenberg, Tim Bunce, Malcolm Beattie.
+Larry Wall, Andy Dougherty, Tom Christiansen, Charles Bailey,
+Nick Ing-Simmons, Chip Salzenberg, Tim Bunce, Malcolm Beattie.
 
 =head2 PUMPKIN?
 
@@ -269,6 +269,9 @@ the pumpking or the pumpkineer.
           5.004_57      1998-Feb-03
           5.004_58      1998-Feb-06
           5.004_59      1998-Feb-13
+          5.004_60      1998-Feb-20
+          5.004_61      1998-Feb-27
+          5.004_62      1998-Mar-06
 
 =head2 SELECTED RELEASE SIZES
 
@@ -305,6 +308,7 @@ explained below.
  5.004_53       1422  62   1295 141    438  70    394 162   1637  56
  5.004_56       1501  66   1301 140    447  74    408 165   1648  57
  5.004_59       1555  72   1317 142    448  74    424 171   1678  58   
+ 5.004_62      1602  77   1327 144    629  92    428 173   1674  58
 
 The "core"..."doc" mean the following files from the Perl source code
 distribution.  The glob notation ** means recursively, (.) means
@@ -360,22 +364,22 @@ the Perl source distribution for somewhat more selected releases.
 
  ======================================================================
 
-            5.003_07 5.004   5.004_04 5.004_59
+            5.003_07 5.004   5.004_04 5.004_62
                                               
- Configure  217  1   225  1  225  1   240  1  
+ Configure  217  1   225  1  225  1   240  1
  cygwin32     -  -    23  5   23  5    23  5  
- djgpp        -  -     -  -    -  -    15  5
+ djgpp        -  -     -  -    -  -    14  5
  eg          54 44    81 62   81 62    81 62
  emacs      143  1   194  1  204  1   212  2
  h2pl        12 12    12 12   12 12    12 12
- hints       90 62   129 69  132 71   139 72
- os2        117 42   121 42  127 42   134 44
+ hints       90 62   129 69  132 71   144 72
+ os2        117 42   121 42  127 42   127 44
  plan9       79 15    82 15   82 15    82 15
- Porting     51  1    94  2  109  4   109  4
+ Porting     51  1    94  2  109  4   203  6
  qnx          -  -     1  2    1  2     1  2
- utils       97  7   112  8  118  8   123  8
- vms        505 27   518 34  524 34   536 34
- win32        -  -   285 33  378 36   464 39
+ utils       97  7   112  8  118  8   124  8
+ vms        505 27   518 34  524 34   538 34
+ win32        -  -   285 33  378 36   470 39
  x2p        280 19   281 19  281 19   281 19
 
 =head2 SELECTED PATCH SIZES
@@ -436,7 +440,7 @@ context diff output format.
           p54rc1        1997-May-12       8   1  11
           p54rc2        1997-May-14       6   0  40
 
-        5.004           1997-May-15       4   0   4
+         5.004          1997-May-15       4   0   4
 
  Tim      5.004_01      1997-Jun-13     222  14  57
           5.004_02      1997-Aug-07     112  16 119

diff --git a/pod/perlop.pod b/pod/perlop.pod
index 5d1aae7..4781b7f 100644 (file)
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -569,7 +569,7 @@ the same character fore and aft, but the 4 sorts of brackets
 
 Note that there can be whitespace between the operator and the quoting
 characters, except when C<#> is being used as the quoting character.
-C<q#foo#> is parsed as being the string C<foo>, which C<q #foo#> is the
+C<q#foo#> is parsed as being the string C<foo>, while C<q #foo#> is the
 operator C<q> followed by a comment. Its argument will be taken from the
 next line. This allows you to write:
 
@@ -670,7 +670,7 @@ C</o> constitutes a promise that you won't change the variables in the pattern.
 If you change them, Perl won't even notice.
 
 If the PATTERN evaluates to a null string, the last
-successfully executed regular expression is used instead.
+successfully matched regular expression is used instead.
 
 If used in a context that requires a list value, a pattern match returns a
 list consisting of the subexpressions matched by the parentheses in the

diff --git a/pod/perlre.pod b/pod/perlre.pod
index 373e1ca..e985377 100644 (file)
--- a/pod/perlre.pod
+++ b/pod/perlre.pod
@@ -278,16 +278,16 @@ matches a word followed by a tab, without including the tab in C<$&>.
 A zero-width negative lookahead assertion.  For example C</foo(?!bar)/>
 matches any occurrence of "foo" that isn't followed by "bar".  Note
 however that lookahead and lookbehind are NOT the same thing.  You cannot
-use this for lookbehind: C</(?!foo)bar/> will not find an occurrence of
-"bar" that is preceded by something which is not "foo".  That's because
+use this for lookbehind.  If you are looking for a "bar" which isn't preceeded
+"foo", C</(?!foo)bar/> will not do what you want.  That's because
 the C<(?!foo)> is just saying that the next thing cannot be "foo"--and
 it's not, it's a "bar", so "foobar" will match.  You would have to do
 something like C</(?!foo)...bar/> for that.   We say "like" because there's
 the case of your "bar" not having three characters before it.  You could
-cover that this way: C</(?:(?!foo)...|^..?)bar/>.  Sometimes it's still
+cover that this way: C</(?:(?!foo)...|^.{0,2})bar/>.  Sometimes it's still
 easier just to say:
 
-    if (/foo/ && $` =~ /bar$/)
+    if (/bar/ && $` !~ /foo$/)
 
 For lookbehind see below.
 
@@ -653,9 +653,18 @@ first alternative includes everything from the last pattern delimiter
 the last alternative contains everything from the last "|" to the next
 pattern delimiter.  For this reason, it's common practice to include
 alternatives in parentheses, to minimize confusion about where they
-start and end.  Note however that "|" is interpreted as a literal with
-square brackets, so if you write C<[fee|fie|foe]> you're really only
-matching C<[feio|]>.
+start and end.
+
+Note that alternatives are tried from left to right, so the first
+alternative found for which the entire expression matches, is the one that
+is chosen. This means that alternatives are not necessarily greedy. For
+example: when mathing C<foo|foot> against "barefoot", only the "foo"
+part will match, as that is the first alternative tried, and it successfully
+matches the target string. (This might not seem important, but it is
+important when you are capturing matched text using parentheses.)
+
+Also note that "|" is interpreted as a literal within square brackets,
+so if you write C<[fee|fie|foe]> you're really only matching C<[feio|]>.
 
 Within a pattern, you may designate subpatterns for later reference by
 enclosing them in parentheses, and you may refer back to the I<n>th

diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 8717349..4bb55bc 100644 (file)
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -29,7 +29,8 @@ Specified line by line via B<-e> switches on the command line.
 =item 2.
 
 Contained in the file specified by the first filename on the command line.
-(Note that systems supporting the #! notation invoke interpreters this way.)
+(Note that systems supporting the #! notation invoke interpreters this
+way. See L<Location of Perl>.)
 
 =item 3.
 
@@ -72,7 +73,7 @@ The sequences "-*" and "- " are specifically ignored so that you could,
 if you were so inclined, say
 
     #!/bin/sh -- # -*- perl -*- -p
-    eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
+    eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
         if $running_under_some_shell;
 
 to let Perl see the B<-p> switch.
@@ -170,6 +171,19 @@ characters as control characters.
 
 There is no general solution to all of this.  It's just a mess.
 
+=head2 Location of Perl
+
+It may seem obvious to say, but Perl is useful only when users can
+easily find it. When possible, it's good for both B</usr/bin/perl> and
+B</usr/local/bin/perl> to be symlinks to the actual binary. If that
+can't be done, system administrators are strongly encouraged to put
+(symlinks to) perl and its accompanying utilities, such as perldoc, into
+a directory typically found along a user's PATH, or in another obvious
+and convenient place.
+
+In this documentation, C<#!/usr/bin/perl> on the first line of the script
+will stand in for whatever method works on your system.
+
 =head2 Switches
 
 A single-character switch may be combined with the following switch, if
@@ -448,7 +462,7 @@ original name fails, and if the name does not already end in one
 of those suffixes.  If your Perl was compiled with DEBUGGING turned
 on, using the -Dp switch to Perl shows how the search progresses.
 
-If the file supplied contains directory separators (i.e. it is an
+If the filename supplied contains directory separators (i.e. it is an
 absolute or relative pathname), and if the file is not found,
 platforms that append file extensions will do so and try to look
 for the file with those extensions added, one by one.
@@ -463,7 +477,7 @@ don't support #!.  This example works on many platforms that
 have a shell compatible with Bourne shell:
 
     #!/usr/bin/perl
-    eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
+    eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
            if $running_under_some_shell;
 
 The system ignores the first line and feeds the script to /bin/sh,
@@ -473,24 +487,27 @@ starts up the Perl interpreter.  On some systems $0 doesn't always
 contain the full pathname, so the B<-S> tells Perl to search for the
 script if necessary.  After Perl locates the script, it parses the
 lines and ignores them because the variable $running_under_some_shell
-is never true.  A better construct than C<$*> would be C<${1+"$@"}>, which
-handles embedded spaces and such in the filenames, but doesn't work if
-the script is being interpreted by csh.  To start up sh rather
+is never true. If the script will be interpreted by csh, you will need
+to replace C<${1+"$@"}> with C<$*>, even though that doesn't understand
+embedded spaces (and such) in the argument list.  To start up sh rather
 than csh, some systems may have to replace the #! line with a line
 containing just a colon, which will be politely ignored by Perl.  Other
 systems can't control that, and need a totally devious construct that
 will work under any of csh, sh, or Perl, such as the following:
 
-       eval '(exit $?0)' && eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
-       & eval 'exec /usr/bin/perl -S $0 $argv:q'
+       eval '(exit $?0)' && eval 'exec /usr/bin/perl -wS $0 ${1+"$@"}'
+       & eval 'exec /usr/bin/perl -wS $0 $argv:q'
                if $running_under_some_shell;
 
 =item B<-T>
 
-forces "taint" checks to be turned on so you can test them.  Ordinarily these checks are
-done only when running setuid or setgid.  It's a good idea to turn
-them on explicitly for programs run on another's behalf, such as CGI
-programs.  See L<perlsec>.
+forces "taint" checks to be turned on so you can test them.  Ordinarily
+these checks are done only when running setuid or setgid.  It's a good
+idea to turn them on explicitly for programs run on another's behalf,
+such as CGI programs.  See L<perlsec>.  Note that (for security reasons)
+this option must be seen by Perl quite early; usually this means it must
+appear early on the command line or in the #! line (for systems which
+support that).
 
 =item B<-u>
 
@@ -619,8 +636,8 @@ look in COMSPEC to find a shell fit for interactive use).
 =item PERL_DEBUG_MSTATS
 
 Relevant only if perl is compiled with the malloc included with the perl
-distribution (that is, if C<perl -V:d_mymalloc> is 'define'),
-if set, this causes memory statistics to be dumped after execution.  If set
+distribution (that is, if C<perl -V:d_mymalloc> is 'define').
+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.
 

diff --git a/pod/perlsec.pod b/pod/perlsec.pod
index 7388479..3fd9034 100644 (file)
--- a/pod/perlsec.pod
+++ b/pod/perlsec.pod
@@ -36,7 +36,9 @@ L<perllocale>), results of certain system calls (readdir, readlink,
 the gecos field of getpw* calls), and all file input are marked as
 "tainted".  Tainted data may not be used directly or indirectly in any
 command that invokes a sub-shell, nor in any command that modifies
-files, directories, or processes.  Any variable set
+files, directories, or processes. (B<Important exception>: If you pass
+a list of arguments to either C<system> or C<exec>, the elements of
+that list are B<NOT> checked for taintedness.) Any variable set
 to a value derived from tainted data will itself be tainted,
 even if it is logically impossible for the tainted data
 to alter the variable.  Because taintedness is associated with each
@@ -88,7 +90,7 @@ For example:
 If you try to do something insecure, you will get a fatal error saying
 something like "Insecure dependency" or "Insecure PATH".  Note that you
 can still write an insecure B<system> or B<exec>, but only by explicitly
-doing something like the last example above.
+doing something like the "considered secure" example above.
 
 =head2 Laundering and Detecting Tainted Data
 
@@ -173,6 +175,14 @@ 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.
 
+The PATH isn't the only environment variable which can cause problems.
+Because some shells may use the variables IFS, CDPATH, ENV, and
+BASH_ENV, Perl checks that those are either empty or untainted when
+starting subprocesses. You may wish to add something like this to your
+setid and taint-checking scripts.
+
+    delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};   # Make %ENV safer
+
 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
 tests in dealing with any user-supplied filenames.  When possible, do

diff --git a/pod/perltrap.pod b/pod/perltrap.pod
index 02abc3b..9d861e3 100644 (file)
--- a/pod/perltrap.pod
+++ b/pod/perltrap.pod
@@ -757,15 +757,11 @@ variable is localized subsequent to the assignment
     # perl4 prints: This is Perl 4
     # perl5 prints:
 
-    # Another example
-
-    *fred = *barney; # fred is aliased to barney
-    @barney = (1, 2, 4);
-    # @fred;
-    print "@fred";  # should print "1, 2, 4"
+=item * (Globs)
 
-    # perl4 prints: 1 2 4
-    # perl5 prints: In string, @fred now must be written as \@fred
+Assigning C<undef> to a glob has no effect in Perl 5.   In Perl 4
+it undefines the associated scalar (but may have other side effects
+including SEGVs).
 
 =item * (Scalar String)
 

diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 221947b..36b4ec4 100644 (file)
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -689,7 +689,7 @@ run-time only. This is a new mechanism and the details may change.
 
 Current state of the interpreter.  Undefined if parsing of the current
 module/eval is not finished (may happen in $SIG{__DIE__} and
-$SIG{__WARN__} handlers).  True if inside an eval, othewise false.
+$SIG{__WARN__} handlers).  True if inside an eval, otherwise false.
 
 =item $BASETIME
 

diff --git a/pod/pod2latex.PL b/pod/pod2latex.PL
index 1d18809..ff8bca6 100644 (file)
--- a/pod/pod2latex.PL
+++ b/pod/pod2latex.PL
@@ -475,6 +475,9 @@ while (<POD>) {
        elsif ($cmd eq 'pod') {
            ;   # recognise the pod directive, as no op (hs)
        }
+       elsif ($cmd eq 'pod') {
+           ;    # recognise the pod directive, as no op (hs)
+       }
        else {
            warn "Unrecognized directive: $cmd\n";
        }

diff --git a/utils/perldoc.PL b/utils/perldoc.PL
index 752f335..bb3d69d 100644 (file)
--- a/utils/perldoc.PL
+++ b/utils/perldoc.PL
@@ -50,6 +50,7 @@ if(@ARGV<1) {
        die <<EOF;
 Usage: $me [-h] [-v] [-t] [-u] [-m] [-l] [-F] [-X] PageName|ModuleName|ProgramName
        $me -f PerlFunc
+       $me -q FAQKeywords
 
 The -h option prints more help.  Also try "perldoc perldoc" to get
 aquainted with the system.
@@ -73,18 +74,20 @@ sub usage{
     die <<EOF;
 perldoc [options] PageName|ModuleName|ProgramName...
 perldoc [options] -f BuiltinFunction
+perldoc [options] -q FAQRegex
 
 Options:
     -h   Display this help message
     -t   Display pod using pod2text instead of pod2man and nroff
              (-t is the default on win32)
     -u  Display unformatted pod text
-    -m   Display modules file in its entirety
-    -l   Display the modules file name
+    -m   Display module's file in its entirety
+    -l   Display the module's file name
     -F   Arguments are file names, not modules
     -v  Verbosely describe what's going on
     -X  use index if present (looks for pod.idx at $Config{archlib})
 
+
 PageName|ModuleName...
          is the name of a piece of documentation that you want to look at. You 
          may either give a descriptive name of the page (as in the case of
@@ -95,7 +98,11 @@ PageName|ModuleName...
 BuiltinFunction
          is the name of a perl function.  Will extract documentation from
          `perlfunc'.
-         
+
+FAQRegex
+         is a regex. Will search perlfaq[1-9] for and extract any
+         questions that match.
+
 Any switches in the PERLDOC environment variable will be used before the 
 command line arguments.  The optional pod index file contains a list of
 filenames, one per line.
@@ -108,7 +115,7 @@ use Text::ParseWords;
 
 unshift(@ARGV,shellwords($ENV{"PERLDOC"}));
 
-getopts("mhtluvFf:X") || usage;
+getopts("mhtluvFf:Xq:") || usage;
 
 usage if $opt_h || $opt_h; # avoid -w warning
 
@@ -125,6 +132,8 @@ if ($opt_t) { require Pod::Text; import Pod::Text; }
 
 if ($opt_f) {
    @pages = ("perlfunc");
+} elsif ($opt_q) {
+   @pages = ("perlfaq1" .. "perlfaq9");
 } else {
    @pages = @ARGV;
 }
@@ -206,11 +215,11 @@ sub minus_f_nocase {
 
 sub check_file {
     my($file) = @_;
-    if ($opt_m) {
-       return minus_f_nocase($file) ? $file : "";
-    } else {
-       return minus_f_nocase($file) && containspod($file) ? $file : "";
-    }
+    $file = minus_f_nocase($file);
+       return "" unless $file;
+       return $file if $::opt_m;
+    return $file if containspod($file);
+    return "";
 }
 
 
@@ -415,6 +424,39 @@ if ($opt_f) {
    exit;
 }
 
+if ($opt_q) {
+   local @ARGV = @found;       # I'm lazy, sue me.
+   my $found = 0;
+   my %found_in;
+   my @pod;
+
+   while (<>) {
+      if (/^=head2\s+.*$opt_q/oi) {
+        $found = 1;
+        push @pod, "=head1 Found in $ARGV\n\n" unless $found_in{$ARGV}++;
+      } elsif (/^=head2/) {
+        $found = 0;
+      }
+      next unless $found;
+      push @pod, $_;
+   }
+   
+   if (@pod) {
+      if ($opt_t) {
+        open(FORMATTER, "| pod2text") || die "Can't start filter";
+        print FORMATTER "=over 8\n\n";
+        print FORMATTER @pod;
+        print FORMATTER "=back\n";
+        close(FORMATTER);
+      } else {
+        print @pod;
+      }
+   } else {
+      die "No documentation for perl function `$opt_f' found\n";
+   }
+   exit;
+}
+
 foreach (@found) {
 
        if($opt_t) {
@@ -548,7 +590,10 @@ command line arguments.  C<perldoc> also searches directories
 specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
 defined) and C<PATH> environment variables.
 (The latter is so that embedded pods for executables, such as
-C<perldoc> itself, are available.)
+C<perldoc> itself, are available.)  C<perldoc> will use, in order of
+preference, the pager defined in C<PERLDOC_PAGER>, C<MANPAGER>, or
+C<PAGER> before trying to find a pager on its own.  (C<MANPAGER> is not
+used if C<perldoc> was told to display plain text or unformatted pod.)
 
 =head1 AUTHOR