7 files changed, 122 insertions, 31 deletions
diff --git a/pod/perldebug.pod b/pod/perldebug.pod
index 7d8d84f3ed..a02fd5c710 100644
--- a/pod/perldebug.pod
+++ b/pod/perldebug.pod
@@ -14,7 +14,8 @@ as we had thought.  Debugging had to be discovered.
 I can remember the exact instant when I realized that
 a large part of my life from then on was going to be
 spent in finding mistakes in my own programs."
---Maurice Wilkes, 1949
+
+I<  --Maurice Wilkes, 1949>
 
 If you invoke Perl with the B<-d> switch, your script runs under the
 Perl source debugger.  This works like an interactive Perl
@@ -941,7 +942,7 @@ package DB, Perl sets the array @DB::args to contain the arguments the
 corresponding stack frame was called with.
 
 If perl is run with B<-d> option, the following additional features
-are enabled:
+are enabled (cf. L<perlvar/$^P>):
 
 =over
 
@@ -1016,16 +1017,13 @@ in the package C<DB>.)
 
 =back
 
-Note that no subroutine call is possible until C<&DB::sub> is defined
-(for subroutines outside of package C<DB>).  (This restriction is
-recently lifted.)
-
-(In fact, for the standard debugger the same is true if C<$DB::deep>
-(how many levels of recursion deep into the debugger you can go before
-a mandatory break) is not defined.)
+Note that if C<&DB::sub> needs some external data to be setup for it
+to work, no subroutine call is possible until this is done.  For the
+standard debugger C<$DB::deep> (how many levels of recursion deep into
+the debugger you can go before a mandatory break) gives an example of
+such a dependency.
 
-With the recent updates the minimal possible debugger consists of one
-line
+The minimal working debugger consists of one line
 
   sub DB::DB {}
 
diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index bfa57c0217..067982258f 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -147,6 +147,13 @@ because at least two widely-used modules depend on the old meaning of
 old (broken) way inside strings; but it generates this message as a
 warning.  And in Perl 5.005, this special treatment will cease.
 
+=head2 Fixed localization of $<digit>, $&, etc.
+
+Perl versions before 5.004 did not always properly localize the
+regex-related special variables.  Perl 5.004 does localize them, as
+the documentation has always said it should.  This may result in $1,
+$2, etc. no longer being set where existing programs use them.
+
 =head2 No resetting of $. on implicit close
 
 The documentation for Perl 5.0 has always stated that C<$.> is I<not>
@@ -285,7 +292,7 @@ there is no C<use English> long name for this variable.
 By default, running out of memory it is not trappable.  However, if
 compiled for this, Perl may use the contents of C<$^M> as an emergency
 pool after die()ing with this message.  Suppose that your Perl were
-compiled with -DEMERGENCY_SBRK and used Perl's malloc.  Then
+compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc.  Then
 
     $^M = 'a' x (1<<16);
 
@@ -495,6 +502,21 @@ before (printed only zeros), but is fine now:
 	$i
     .
 
+However, it still fails (without a warning) if the foreach is within a
+subroutine:
+
+    my $i;
+    sub foo {
+      foreach $i ( 1 .. 10 ) {
+	write;
+      }
+    }
+    foo;
+    format =
+	my i is @#
+	$i
+    .
+
 =back
 
 =head2 New builtin methods
@@ -631,24 +653,23 @@ possibly for cleaning up.
 
 =head2 Malloc enhancements
 
-Four new compilation flags are recognized by malloc.c.  (They have no
-effect if perl is compiled with system malloc().)
-
-=over
-
-=item -DDEBUGGING_MSTATS
-
-If perl is compiled with C<DEBUGGING_MSTATS> defined, you can print
+If perl is compiled with the malloc included with the perl distribution
+(that is, if C<perl -V:d_mymalloc> is 'define') then you can print
 memory statistics at runtime by running Perl thusly:
 
   env PERL_DEBUG_MSTATS=2 perl your_script_here
 
 The value of 2 means to print statistics after compilation and on
-exit; with a value of 1, the statistics ares printed only on exit.
+exit; with a value of 1, the statistics are printed only on exit.
 (If you want the statistics at an arbitrary time, you'll need to
 install the optional module Devel::Peek.)
 
-=item -DEMERGENCY_SBRK
+Three new compilation flags are recognized by malloc.c.  (They have no
+effect if perl is compiled with system malloc().)
+
+=over
+
+=item -DPERL_EMERGENCY_SBRK
 
 If this macro is defined, running out of memory need not be a fatal
 error: a memory pool can allocated by assigning to the special
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index c0eb857eac..0d9ee55eb8 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -277,6 +277,15 @@ could indicate that SvREFCNT_dec() was called too many times, or that
 SvREFCNT_inc() was called too few times, or that the SV was mortalized
 when it shouldn't have been, or that memory has been corrupted.
 
+=item Attempt to pack pointer to temporary value
+
+(W) You tried to pass a temporary value (like the result of a
+function, or a computed expression) to the "p" pack() template.  This
+means the result contains a pointer to a location that could become
+invalid anytime, even before the end of the current statement.  Use
+literals or global values as arguments to the "p" pack() template to
+avoid this warning.
+
 =item Attempt to use reference as lvalue in substr
 
 (W) You supplied a reference as the first argument to substr() used
@@ -386,6 +395,11 @@ like a block, except that it isn't a proper block.  This usually
 occurs if you tried to jump out of a sort() block or subroutine, which
 is a no-no.  See L<perlfunc/goto>.
 
+=item Can't "goto" into the middle of a foreach loop
+
+(F) A "goto" statement was executed to jump into the middle of a
+foreach loop.  You can't get there from here.  See L<perlfunc/goto>.
+
 =item Can't "last" outside a block
 
 (F) A "last" statement was executed to break out of the current block,
diff --git a/pod/perlembed.pod b/pod/perlembed.pod
index e1ab91eaba..c43ed556aa 100644
--- a/pod/perlembed.pod
+++ b/pod/perlembed.pod
@@ -1010,7 +1010,7 @@ Dov Grobgeld, and Ilya Zakharevich.
 Check out Doug's article on embedding in Volume 1, Issue 4 of The Perl
 Journal.  Info about TPJ is available from http://tpj.com.
 
-April 14, 1997
+July 17, 1997
 
 Some of this material is excerpted from Jon Orwant's book: I<Perl 5
 Interactive>, Waite Group Press, 1996 (ISBN 1-57169-064-6) and appears
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index cc9fa00238..4bf1fdabb1 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -2156,8 +2156,11 @@ types gobble just one value, but pack it as a string of length count,
 padding with nulls or spaces as necessary.  (When unpacking, "A" strips
 trailing spaces and nulls, but "a" does not.)  Likewise, the "b" and "B"
 fields pack a string that many bits long.  The "h" and "H" fields pack a
-string that many nybbles long.  The "P" packs a pointer to a structure of
-the size indicated by the length.  Real numbers (floats and doubles) are
+string that many nybbles long.  The "p" type packs a pointer to a null-
+terminated string.  You are responsible for ensuring the string is not a
+temporary value (which can potentially get deallocated before you get
+around to using the packed result).  The "P" packs a pointer to a structure
+of the size indicated by the length.  Real numbers (floats and doubles) are
 in the native machine format only; due to the multiplicity of floating
 formats around, and the lack of a standard "network" representation, no
 facility for interchange has been made.  This means that packed floating
@@ -2377,6 +2380,16 @@ chdir() there, it would have been testing the wrong file.
     @dots = grep { /^\./ && -f "$some_dir/$_" } readdir(DIR);
     closedir DIR;
 
+=item readline EXPR
+
+Reads from the file handle EXPR.  In scalar context, a single line
+is read and returned.  In list context, reads until end-of-file is
+reached and returns a list of lines (however you've defined lines
+with $/ or $INPUT_RECORD_SEPARATOR).
+This is the internal function implementing the C<E<lt>EXPRE<gt>>
+operator, but you can use it directly.  The C<E<lt>EXPRE<gt>>
+operator is discussed in more detail in L<perlop/"I/O Operators">.
+
 =item readlink EXPR
 
 =item readlink
@@ -2386,6 +2399,17 @@ implemented.  If not, gives a fatal error.  If there is some system
 error, returns the undefined value and sets C<$!> (errno).  If EXPR is
 omitted, uses $_.
 
+=item readpipe EXPR
+
+EXPR is interpolated and then executed as a system command.
+The collected standard output of the command is returned.
+In scalar context, it comes back as a single (potentially
+multi-line) string.  In list context, returns a list of lines
+(however you've defined lines with $/ or $INPUT_RECORD_SEPARATOR).
+This is the internal function implementing the C<qx/EXPR/>
+operator, but you can use it directly.  The C<qx/EXPR/>
+operator is discussed in more detail in L<perlop/"I/O Operators">.
+
 =item recv SOCKET,SCALAR,LEN,FLAGS
 
 Receives a message on a socket.  Attempts to receive LENGTH bytes of
@@ -3342,11 +3366,15 @@ L<perlref> for details.
 
 Extracts a substring out of EXPR and returns it.  First character is at
 offset 0, or whatever you've set C<$[> to (but don't do that).
-If OFFSET is negative, starts
+If OFFSET is negative (or more precisely, less than C<$[>), starts
 that far from the end of the string.  If LEN is omitted, returns
 everything to the end of the string.  If LEN is negative, leaves that
 many characters off the end of the string.
 
+If you specify a substring which is partly outside the string, the part
+within the string is returned.    If the substring is totally outside
+the string a warning is produced.
+
 You can use the substr() function
 as an lvalue, in which case EXPR must be an lvalue.  If you assign
 something shorter than LEN, the string will shrink, and if you assign
diff --git a/pod/perltoc.pod b/pod/perltoc.pod
index 989c1efe01..74b0029d73 100644
--- a/pod/perltoc.pod
+++ b/pod/perltoc.pod
@@ -911,7 +911,7 @@ LIST, READLINE this, GETC this, DESTROY this
 
 =item Malloc enhancements
 
--DDEBUGGING_MSTATS, -DEMERGENCY_SBRK, -DPACK_MALLOC, -DTWO_POT_OPTIMIZE
+-DDEBUGGING_MSTATS, -DPERL_EMERGENCY_SBRK, -DPACK_MALLOC, -DTWO_POT_OPTIMIZE
 
 =item Miscellaneous efficiency enhancements
 
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 198e5c12a3..6487fdda36 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -619,9 +619,39 @@ is identical to C<$Config{'osname'}>.
 
 =item $^P
 
-The internal flag that the debugger clears so that it doesn't debug
-itself.  You could conceivably disable debugging yourself by clearing
-it.
+The internal variable for debugging support.  Different bits mean the
+following (subject to change): 
+
+=over 6
+
+=item 0x01
+
+Debug subroutine enter/exit.
+
+=item 0x02
+
+Line-by-line debugging.
+
+=item 0x04
+
+Switch off optimizations.
+
+=item 0x08
+
+Preserve more data for future interactive inspections.
+
+=item 0x10
+
+Keep info about source lines on which a subroutine is defined.
+
+=item 0x20
+
+Start with single-step on.
+
+=back
+
+Note that some bits may be relevent at compile-time only, some at
+run-time only. This is a new mechanism and the details may change.
 
 =item $BASETIME
 
@@ -753,7 +783,7 @@ L<perlfunc/die>, L<perlfunc/warn> and L<perlfunc/eval>.
 By default, running out of memory it is not trappable.  However, if
 compiled for this, Perl may use the contents of C<$^M> as an emergency
 pool after die()ing with this message.  Suppose that your Perl were
-compiled with -DEMERGENCY_SBRK and used Perl's malloc.  Then
+compiled with -DPERL_EMERGENCY_SBRK and used Perl's malloc.  Then
 
     $^M = 'a' x (1<<16);