patch for LWP 5.05 to make it play with both 5.003 and 5.003_20 + overload patch

6 files changed, 388 insertions, 77 deletions

diff --git a/pod/perldebug.pod b/pod/perldebug.pod
index 77502f27d3..8e595f54e4 100644
--- a/pod/perldebug.pod
+++ b/pod/perldebug.pod
@@ -60,12 +60,17 @@ it's run through your pager, as in
 
     DB> |h
 
+You may change the pager which is used via C<O pager=...> command.
+
 =item p expr
 
 Same as C<print {$DB::OUT} expr> in the current package.  In particular,
 because this is just Perl's own B<print> function, this means that nested
 data structures and objects are not dumped, unlike with the C<x> command.
 
+The C<DB::OUT> filehandle is opened to F</dev/tty>, regardless of
+where STDOUT may be redirected to.
+
 =item x expr
 
 Evaluates its expression in list context and dumps out the result 
@@ -105,10 +110,12 @@ Single step.  Executes until it reaches the beginning of another
 statement, descending into subroutine calls.  If an expression is
 supplied that includes function calls, it too will be single-stepped.
 
-=item n
+=item n [expr]
 
 Next.  Executes over subroutine calls, until it reaches the beginning
-of the next statement.
+of the next statement. If an expression is
+supplied that includes function calls, it too will be executed with
+stops before each statement.
 
 =item E<lt>CRE<gt>
 
@@ -129,7 +136,7 @@ List C<incr+1> lines starting at C<min>.
 
 =item l min-max
 
-List lines C<min> through C<max>.
+List lines C<min> through C<max>. C<l -> is synonymous to C<->.
 
 =item l line
 
@@ -154,7 +161,9 @@ print it out.
 
 =item f filename
 
-Switch to viewing a different file.
+Switch to viewing a different file or eval statement. If C<filename>
+is not a full filename as found in values of %INC, it is considered as
+a regexp.
 
 =item /pattern/
 
@@ -235,7 +244,13 @@ Set breakpoint at first line of subroutine after it is compiled.
 
 =item b load filename
 
-Set breakpoint at the first executed line of the file.
+Set breakpoint at the first executed line of the file. Filename should
+be a full name as found in values of %INC.
+
+=item b compile subname
+
+Sets breakpoint at the first statement executed after the subroutine
+is compiled.
 
 =item d [line]
 
@@ -273,34 +288,41 @@ be abbreviated.  Several options can be listed.
 
 =over 12
 
-=item recallCommand, ShellBang
+=item C<recallCommand>, C<ShellBang>
 
 The characters used to recall command or spawn shell.  By
 default, these are both set to C<!>.
 
-=item pager
+=item C<pager>
 
 Program to use for output of pager-piped commands (those
 beginning with a C<|> character.)  By default,
 C<$ENV{PAGER}> will be used.
 
-=item tkRunning
+=item C<tkRunning>
 
 Run Tk while prompting (with ReadLine).
 
-=item signalLevel, warnLevel, dieLevel
+=item C<signalLevel>, C<warnLevel>, C<dieLevel>
+
+Level of verbosity. By default the debugger is in a sane verbose mode,
+thus it will print backtraces on all the warnings and die-messages
+which are going to be printed out, and will print a message when
+interesting uncaught signals arrive. 
 
-Level of verbosity.
+To disable this behaviour, set these values to 0. If C<dieLevel> is 2,
+then the messages which will be caught by surrounding C<eval> are also
+printed.
 
-=item AutoTrace
+=item C<AutoTrace>
 
-Where to print all the breakable points in the executed program
-(similar to C<t> command, but can be put into C<PERLDB_OPTS>).
+Trace mode (similar to C<t> command, but can be put into
+C<PERLDB_OPTS>).
 
-=item LineInfo
+=item C<LineInfo>
 
-File or pipe to print line number info to.  If it is a
-pipe, then a short, "emacs like" message is used.
+File or pipe to print line number info to.  If it is a pipe (say,
+C<|visual_perl_db>), then a short, "emacs like" message is used.
 
 =item C<inhibit_exit>
 
@@ -317,7 +339,14 @@ C<frame & 2> is false, messages are printed on entry only. (Printing
 on exit may be useful if inter(di)spersed with other messages.)
 
 If C<frame & 4>, arguments to functions are printed as well as the
-context and caller info.
+context and caller info. If C<frame & 8>, overloaded C<stringify> and
+C<tie>d C<FETCH> are enabled on the printed arguments. The length at
+which the argument list is truncated is governed by the next option:
+
+=item C<maxTraceLen>
+
+length at which the argument list is truncated when C<frame> option's
+bit 4 is set.
 
 =back
 
@@ -326,29 +355,38 @@ commands:
 
 =over 12
 
-=item arrayDepth, hashDepth
+=item C<arrayDepth>, C<hashDepth>
 
 Print only first N elements ('' for all).
 
-=item compactDump, veryCompact
+=item C<compactDump>, C<veryCompact>
 
-Change style of array and hash dump.
+Change style of array and hash dump. If C<compactDump>, short array
+may be printed on one line.
 
-=item globPrint
+=item C<globPrint>
 
 Whether to print contents of globs.
 
-=item DumpDBFiles
+=item C<DumpDBFiles>
 
 Dump arrays holding debugged files.
 
-=item DumpPackages
+=item C<DumpPackages>
 
 Dump symbol tables of packages.
 
-=item quote, HighBit, undefPrint
+=item C<quote>, C<HighBit>, C<undefPrint>
+
+Change style of string dump. Default value of C<quote> is C<auto>, one
+can enable either double-quotish dump, or single-quotish by setting it
+to C<"> or C<'>. By default, characters with high bit set are printed
+I<as is>.
+
+=item C<UsageOnly> 
 
-Change style of string dump.
+I<very> rudimentally per-package memory usage dump. Calculates total
+size of strings in variables in the package.
 
 =back
 
@@ -358,7 +396,7 @@ C<ReadLine>, and C<NonStop> there.
 
 Example rc file:
 
-    &parse_options("NonStop=1 LineInfo=db.out AutoTrace");
+  &parse_options("NonStop=1 LineInfo=db.out AutoTrace");
 
 The script will run without human intervention, putting trace information
 into the file I<db.out>.  (If you interrupt it, you would better reset
@@ -370,13 +408,6 @@ C<LineInfo> to something "interactive"!)
 
 The TTY to use for debugging I/O.
 
-=item noTTY
-
-If set, goes in C<NonStop> mode.  On interrupt if TTY is not set uses the
-value of C<noTTY> or "/tmp/perldbtty$$" to find TTY using
-C<Term::Rendezvous>.  Current variant is to have the name of TTY in this
-file.
-
 =item C<noTTY>
 
 If set, goes in C<NonStop> mode, and would not connect to a TTY. If
@@ -405,7 +436,7 @@ programmatically by setting $DB::signal or $DB::single.
 
 Here's an example of using the C<$ENV{PERLDB_OPTS}> variable:
 
-        $ PERLDB_OPTS="N f=2" perl -d myprogram
+  $ PERLDB_OPTS="N f=2" perl -d myprogram
 
 will run the script C<myprogram> without human intervention, printing
 out the call tree with entry and exit points.  Note that C<N f=2> is
@@ -416,7 +447,7 @@ C<Dump*> options).
 
 Other examples may include
 
-        $ PERLDB_OPTS="N f A L=listing" perl -d myprogram
+  $ PERLDB_OPTS="N f A L=listing" perl -d myprogram
 
 - runs script non-interactively, printing info on each entry into a
 subroutine and each executed line into the file F<listing>. (If you
@@ -424,13 +455,13 @@ interrupt it, you would better reset C<LineInfo> to something
 "interactive"!)
 
 
-        $ env "PERLDB_OPTS=R=0 TTY=/dev/ttyc" perl -d myprogram
+  $ env "PERLDB_OPTS=R=0 TTY=/dev/ttyc" perl -d myprogram
 
 may be useful for debugging a program which uses C<Term::ReadLine>
 itself. Do not forget detach shell from the TTY in the window which
 corresponds to F</dev/ttyc>, say, by issuing a command like
 
-	$ sleep 1000000
+  $ sleep 1000000
 
 See L<"Debugger Internals"> below for more details.
 
@@ -527,20 +558,34 @@ output, such as
 
 =item = [alias value]
 
-Define a command alias, or list current aliases.
+Define a command alias, like
+
+    = quit q
+
+or list current aliases.
 
 =item command
 
 Execute command as a Perl statement.  A missing semicolon will be
 supplied.
 
-=item p expr
+=item m expr
 
-Same as C<print DB::OUT expr>.  The DB::OUT filehandle is opened to
-/dev/tty, regardless of where STDOUT may be redirected to.
+The expression is evaluated, and the methods which may be applied to
+the result are listed.
+
+=item m package
+
+The methods which may be applied to objects in the C<package> are listed.
 
 =back
 
+=head2 Debugger input/output
+
+=over 8
+
+=item Prompt
+
 The debugger prompt is something like
 
     DB<8>
@@ -557,9 +602,12 @@ you'd already at a breakpoint and then printed out the result of a
 function call that itself also has a breakpoint, or you step into an
 expression via C<s/n/t expression> command.
 
+=item Multi-line commands
+
 If you want to enter a multi-line command, such as a subroutine
-definition with several statements, you may escape the newline that would
-normally end the debugger command with a backslash.  Here's an example:
+definition with several statements, or a format, you may escape the
+newline that would normally end the debugger command with a backslash.
+Here's an example:
 
       DB<1> for (1..4) {         \
       cont:     print "ok\n";   \
@@ -572,7 +620,10 @@ normally end the debugger command with a backslash.  Here's an example:
 Note that this business of escaping a newline is specific to interactive
 commands typed into the debugger.
 
-Here's an example of what a stack back-trace might look like:
+=item Stack backtrace
+
+Here's an example of what a stack back-trace via C<T> command might
+look like:
 
     $ = main::infested called from file `Ambulation.pm' line 10
     @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
@@ -589,6 +640,160 @@ I<camel_flea> file with four arguments.  The last stack frame shows that
 C<main::pests> was called in a scalar context, also from I<camel_flea>,
 but from line 4.
 
+Note that if you execute C<T> command from inside an active C<use>
+statement, the backtrace will contain both C<L<perlfunc/require>>
+frame and an C<L<perlfunc/eval EXPR>>) frame.
+
+=item Listing
+
+Listing given via different flavors of C<l> command looks like this:
+
+    DB<<13>> l
+  101:                @i{@i} = ();
+  102:b               @isa{@i,$pack} = ()
+  103                     if(exists $i{$prevpack} || exists $isa{$pack});
+  104             }
+  105
+  106             next
+  107==>              if(exists $isa{$pack});
+  108
+  109:a           if ($extra-- > 0) {
+  110:                %isa = ($pack,1);
+
+Note that the breakable lines are marked with C<:>, lines with
+breakpoints are marked by C<b>, with actions by C<a>, and the
+next executed line is marked by C<==E<gt>>.
+
+=item Frame listing
+
+When C<frame> option is set, debugger would print entered (and
+optionally exited) subroutines in different styles.
+
+What follows is the start of the listing of 
+
+  env "PERLDB_OPTS=f=1 N" perl -d -V
+
+=over 4
+
+=item 1
+
+  entering main::BEGIN
+   entering Config::BEGIN
+    Package lib/Exporter.pm.
+    Package lib/Carp.pm.
+   Package lib/Config.pm.
+   entering Config::TIEHASH
+   entering Exporter::import
+    entering Exporter::export
+  entering Config::myconfig
+   entering Config::FETCH
+   entering Config::FETCH
+   entering Config::FETCH
+   entering Config::FETCH
+
+=item 2
+
+  entering main::BEGIN
+   entering Config::BEGIN
+    Package lib/Exporter.pm.
+    Package lib/Carp.pm.
+   exited Config::BEGIN
+   Package lib/Config.pm.
+   entering Config::TIEHASH
+   exited Config::TIEHASH
+   entering Exporter::import
+    entering Exporter::export
+    exited Exporter::export
+   exited Exporter::import
+  exited main::BEGIN
+  entering Config::myconfig
+   entering Config::FETCH
+   exited Config::FETCH
+   entering Config::FETCH
+   exited Config::FETCH
+   entering Config::FETCH
+
+=item 4
+
+  in  $=main::BEGIN() from /dev/nul:0
+   in  $=Config::BEGIN() from lib/Config.pm:2
+    Package lib/Exporter.pm.
+    Package lib/Carp.pm.
+   Package lib/Config.pm.
+   in  $=Config::TIEHASH('Config') from lib/Config.pm:644
+   in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
+    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from li
+  in  @=Config::myconfig() from /dev/nul:0
+   in  $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
+   in  $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
+   in  $=Config::FETCH(ref(Config), 'PATCHLEVEL') from lib/Config.pm:574
+   in  $=Config::FETCH(ref(Config), 'SUBVERSION') from lib/Config.pm:574
+   in  $=Config::FETCH(ref(Config), 'osname') from lib/Config.pm:574
+   in  $=Config::FETCH(ref(Config), 'osvers') from lib/Config.pm:574
+
+=item 6
+
+  in  $=main::BEGIN() from /dev/nul:0
+   in  $=Config::BEGIN() from lib/Config.pm:2
+    Package lib/Exporter.pm.
+    Package lib/Carp.pm.
+   out $=Config::BEGIN() from lib/Config.pm:0
+   Package lib/Config.pm.
+   in  $=Config::TIEHASH('Config') from lib/Config.pm:644
+   out $=Config::TIEHASH('Config') from lib/Config.pm:644
+   in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
+    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
+    out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/
+   out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
+  out $=main::BEGIN() from /dev/nul:0
+  in  @=Config::myconfig() from /dev/nul:0
+   in  $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
+   out $=Config::FETCH(ref(Config), 'package') from lib/Config.pm:574
+   in  $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
+   out $=Config::FETCH(ref(Config), 'baserev') from lib/Config.pm:574
+   in  $=Config::FETCH(ref(Config), 'PATCHLEVEL') from lib/Config.pm:574
+   out $=Config::FETCH(ref(Config), 'PATCHLEVEL') from lib/Config.pm:574
+   in  $=Config::FETCH(ref(Config), 'SUBVERSION') from lib/Config.pm:574
+
+=item 14
+
+  in  $=main::BEGIN() from /dev/nul:0
+   in  $=Config::BEGIN() from lib/Config.pm:2
+    Package lib/Exporter.pm.
+    Package lib/Carp.pm.
+   out $=Config::BEGIN() from lib/Config.pm:0
+   Package lib/Config.pm.
+   in  $=Config::TIEHASH('Config') from lib/Config.pm:644
+   out $=Config::TIEHASH('Config') from lib/Config.pm:644
+   in  $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
+    in  $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
+    out $=Exporter::export('Config', 'main', 'myconfig', 'config_vars') from lib/E
+   out $=Exporter::import('Config', 'myconfig', 'config_vars') from /dev/nul:0
+  out $=main::BEGIN() from /dev/nul:0
+  in  @=Config::myconfig() from /dev/nul:0
+   in  $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
+   out $=Config::FETCH('Config=HASH(0x1aa444)', 'package') from lib/Config.pm:574
+   in  $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
+   out $=Config::FETCH('Config=HASH(0x1aa444)', 'baserev') from lib/Config.pm:574
+
+=back
+
+In all the cases indentation of lines shows the call tree, if bit 2 of
+C<frame> is set, then a line is printed on exit from a subroutine as
+well, if bit 4 is set, then the arguments are printed as well as the
+caller info, if bit 8 is set, the arguments are printed even if they
+are tied or references.
+
+When a package is compiled, a line like this
+
+    Package lib/Carp.pm.
+
+is printed with proper indentation.
+
+=back
+
+=head2 Debugging compile-time statements
+
 If you have any compile-time executable statements (code within a BEGIN
 block or a C<use> statement), these will C<NOT> be stopped by debugger,
 although C<require>s will (and compile-time statements can be traced
@@ -604,6 +809,15 @@ just typed the C<n> command, whereas a value of 1 means the C<s>
 command.  The C<$DB::trace>  variable should be set to 1 to simulate
 having typed the C<t> command.
 
+Another way to debug compile-time code is to start debugger, set a
+breakpoint on I<load> of some module thusly
+
+    DB<7> b load f:/perllib/lib/Carp.pm
+  Will stop on load of `f:/perllib/lib/Carp.pm'.
+
+and restart debugger by C<R> command (if possible). One can use C<b
+compile subname> for the same purpose.
+
 =head2 Debugger Customization
 
 Most probably you not want to modify the debugger, it contains enough
@@ -647,6 +861,10 @@ the Term::ReadKey and Term::ReadLine modules from CPAN, you will
 have full editing capabilities much like GNU I<readline>(3) provides.
 Look for these in the F<modules/by-module/Term> directory on CPAN.
 
+A rudimentary command-line completion is also available.
+Unfortunately, the names of lexical variables are not available for
+completion.
+
 =head2 Editor Support for Debugging
 
 If you have GNU B<emacs> installed on your system, it can interact with
@@ -683,9 +901,9 @@ in that profile.
 
 =head2 Debugger support in perl
 
-When you call the B<caller> function from package DB, Perl sets the
-C<@DB::args> array to contain the arguments that stack frame was called
-with.  
+When you call the B<caller> function (see L<perlfunc/caller>) from the
+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:
@@ -752,7 +970,7 @@ a breakpoint, a call to C<DB::DB()> is performed if any one of
 variables $DB::trace, $DB::single, or $DB::signal is true. (Note that
 these variables are not C<local>izable.) This feature is disabled when
 the control is inside C<DB::DB()> or functions called from it (unless
-C<$^D & 1 E<lt>E<lt> 30>).
+C<$^D & (1E<lt>E<lt>30)>).
 
 =item *
 
@@ -764,10 +982,42 @@ 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>).  (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.)
+(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.)
+
+With the recent updates the minimal possible debugger consists of one
+line
+
+  sub DB::DB {}
+
+which is quite handy as contents of C<PERL5DB> environment
+variable:
+
+  env "PERL5DB=sub DB::DB {}" perl -d your-script
+
+Another (a little bit more useful) minimal debugger can be created
+with the only line being
+
+  sub DB::DB {print ++$i; scalar <STDIN>}
+
+This debugger would print the sequential number of encountered
+statement, and would wait for your C<CR> to continue.
+
+The following debugger is quite functional:
+
+  { 
+    package DB; 
+    sub DB  {} 
+    sub sub {print ++$i, " $sub\n"; &$sub}
+  }
+
+It prints the sequential number of subroutine call and the name of the
+called subroutine. Note that C<&DB::sub> should be compiled into the
+package C<DB>.
 
 =head2 Debugger Internals
 
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index d08d2dc452..68cc69d758 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -799,6 +799,12 @@ Perhaps you need to copy the value to a temporary, and repeat that.
 (F) The create routine failed for some reason while trying to process
 a B<-e> switch.  Maybe your /tmp partition is full, or clobbered.
 
+=item Cannot resolve method `%s' overloading `%s' in package `%s'
+
+(F|P) Error resolving overloading specified by a method name (as
+opposed to a subroutine reference): no such method callable via the
+package. If method name is C<???>, this is an internal error.
+
 =item chmod: mode argument is missing initial 0
 
 (W) A novice will sometimes say
@@ -823,6 +829,10 @@ the return value of your socket() call?  See L<perlfunc/connect>.
 inlining.  See L<perlsub/"Constant Functions"> for commentary and
 workarounds.
 
+=item Copy method did not return a reference
+
+(F) The method which overloads "=" is buggy. See L<overload/Copy Constructor>.
+
 =item Corrupt malloc ptr 0x%lx at 0x%lx
 
 (P) The malloc package that comes with Perl had an internal failure.
@@ -1177,7 +1187,7 @@ assume that an unbackslashed @ interpolates an array.)
 =item Method for operation %s not found in package %s during blessing
 
 (F) An attempt was made to specify an entry in an overloading table that
-doesn't somehow point to a valid method.  See L<overload>.
+doesn't resolve to a valid subroutine.  See L<overload>.
 
 =item Might be a runaway multi-line %s string starting on line %d
 
@@ -1420,7 +1430,7 @@ subroutine), but found a reference to something else instead.  You can
 use the ref() function to find out what kind of ref it really was.
 See also L<perlref>.
 
-=item Not a subroutine reference in %OVERLOAD
+=item Not a subroutine reference in overload table
 
 (F) An attempt was made to specify an entry in an overloading table that
 doesn't somehow point to a valid subroutine.  See L<overload>.
@@ -1487,21 +1497,13 @@ will extend the buffer and zero pad the new area.
 
 (S) An internal warning that the grammar is screwed up.
 
-=item Operation `%s' %s: no method found,
-
-(F) An attempt was made to use an entry in an overloading table that
-somehow no longer points to a valid method.  See L<overload>.
-
-=item Stub found while resolving method `%s' overloading `%s' in package `%s'
-
-(P) Overloading resolution over @ISA tree may be broken by importing stubs.
-Stubs should never be implicitely created, but explicit calls to C<can>
-may break this.
+=item Operation `%s': no method found,%s
 
-=item Cannot resolve method `%s' overloading `%s' in package `s'
-
-(P) Internal error trying to resolve overloading specified by a method
-name (as opposed to a subroutine reference).
+(F) An attempt was made to perform an overloaded operation for which
+no handler was defined.  While some handlers can be autogenerated in
+terms of other handlers, there is no default handler for any
+operation, unless C<fallback> overloading key is specified to be
+true.  See L<overload>.
 
 =item Operator or semicolon missing before %s
 
@@ -2002,6 +2004,12 @@ there was a failure.  You probably wanted to use system() instead,
 which does return.  To suppress this warning, put the exec() in a block
 by itself.
 
+=item Stub found while resolving method `%s' overloading `%s' in package `%s'
+
+(P) Overloading resolution over @ISA tree may be broken by importation stubs.
+Stubs should never be implicitely created, but explicit calls to C<can>
+may break this.
+
 =item Subroutine %s redefined
 
 (W) You redefined a subroutine.  To suppress this warning, say
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 488c797c65..34d9281835 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -408,8 +408,17 @@ With EXPR, it returns some extra information that the debugger uses to
 print a stack trace.  The value of EXPR indicates how many call frames
 to go back before the current one.
 
-    ($package, $filename, $line,
-     $subroutine, $hasargs, $wantarray) = caller($i);
+    ($package, $filename, $line, $subroutine, 
+     $hasargs, $wantarray, $evaltext, $is_require) = caller($i);
+
+Here $subroutine may be C<"(eval)"> if the frame is not a subroutine
+call, but C<L<eval>>. In such a case additional elements $evaltext and
+$is_require are set: $is_require is true if the frame is created by
+C<L<require>> or C<L<use>> statement, $evaltext contains the text of
+C<L<eval EXPR>> statement. In particular, for C<L<eval BLOCK>>
+statement $filename is C<"(eval)">, but $evaltext is undefined. (Note
+also that C<L<use>> statement creates a C<L<require>> frame inside
+an C<L<eval EXPR>>) frame.
 
 Furthermore, when called from within the DB package, caller returns more
 detailed information: it sets the list variable @DB::args to be the
diff --git a/pod/perlop.pod b/pod/perlop.pod
index dd3aeab663..55108f0328 100644
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -737,6 +737,32 @@ The last example should print:
 Note how C<m//g> matches change the value reported by C<pos()>, but the
 non-global match doesn't.
 
+A useful idiom for C<lex>-like scanners is C</\G.../g>. You can
+combine several regexps like this to process a string part-by-part,
+doing different actions depending on which regexp matched.  The next
+regexp would step in at the place the previous one left off.
+
+    $_ = <<'EOL';
+      $url = new URI::URL "http://www/";   die if $url eq "xXx";
+EOL
+  LOOP:
+    {
+      print(" digits"),		redo LOOP if /\G\d+\b[,.;]?\s*/g;
+      print(" lowercase"),	redo LOOP if /\G[a-z]+\b[,.;]?\s*/g;
+      print(" UPPERCASE"),	redo LOOP if /\G[A-Z]+\b[,.;]?\s*/g;
+      print(" Capitalized"),	redo LOOP if /\G[A-Z][a-z]+\b[,.;]?\s*/g;
+      print(" MiXeD"),		redo LOOP if /\G[A-Za-z]+\b[,.;]?\s*/g;
+      print(" alphanumeric"),	redo LOOP if /\G[A-Za-z0-9]+\b[,.;]?\s*/g;
+      print(" line-noise"),	redo LOOP if /\G[^A-Za-z0-9]+/g;
+      print ". That's all!\n";
+    }
+
+Here is the output (split into several lines):
+
+ line-noise lowercase line-noise lowercase UPPERCASE line-noise
+ UPPERCASE line-noise lowercase line-noise lowercase line-noise
+ lowercase lowercase line-noise lowercase lowercase line-noise
+ MiXeD line-noise. That's all!
 
 =item q/STRING/
 
diff --git a/pod/perlre.pod b/pod/perlre.pod
index a4c0a7d9de..cb3ce032d0 100644
--- a/pod/perlre.pod
+++ b/pod/perlre.pod
@@ -175,7 +175,11 @@ just like "^" and "$" except that they won't match multiple times when the
 C</m> modifier is used, while "^" and "$" will match at every internal line
 boundary.  To match the actual end of the string, not ignoring newline,
 you can use C<\Z(?!\n)>.  The C<\G> assertion can be used to mix global
-matches (using C<m//g>) and non-global ones, as described in L<perlop>.
+matches (using C<m//g>) and non-global ones, as described in 
+L<perlop/"Regexp Quote-Like Operators">.
+It is also useful when writing C<lex>-like scanners, when you have several
+regexps which you want to match against consequent substrings of your
+string, see the previous reference.
 The actual location where C<\G> will match can also be influenced
 by using C<pos()> as an lvalue.  See L<perlfunc/pos>.
 
diff --git a/pod/perlxs.pod b/pod/perlxs.pod
index 26418b51a9..35d74e9eed 100644
--- a/pod/perlxs.pod
+++ b/pod/perlxs.pod
@@ -167,7 +167,21 @@ be received by Perl as the return value of the XSUB.
 
 If the XSUB has a return type of C<void> then the compiler will
 not supply a RETVAL variable for that function.  When using
-the PPCODE: directive the RETVAL variable may not be needed.
+the PPCODE: directive the RETVAL variable is not needed, unless used
+explicitly.
+
+If PPCODE: directive is not used, C<void> return value should be used
+only for subroutines which do not return a value, I<even if> CODE:
+directive is used which sets ST(0) explicitly. 
+
+Older versions of this document recommended to use C<void> return
+value in such cases. It was discovered that this could lead to
+segfaults in cases when XSUB was I<truely> C<void>. This practice is
+now deprecated, and may be not supported at some future version. Use
+the return value C<SV *> in such cases. (Currently C<xsubpp> contains
+some heuristic code which tries to disambiguate between "truely-void"
+and "old-practice-declared-as-void" functions. Hence your code is at
+mercy of this heuristics unless you use C<SV *> as return value.)
 
 =head2 The MODULE Keyword
 
@@ -570,13 +584,13 @@ of $timep will either be undef or it will be a valid time.
 
      $timep = rpcb_gettime( "localhost" );
 
-The following XSUB uses the C<void> return type to disable the generation of
-the RETVAL variable and uses a CODE: block to indicate to the compiler
+The following XSUB uses the C<SV *> return type as a mneumonic only,
+and uses a CODE: block to indicate to the compiler
 that the programmer has supplied all the necessary code.  The
 sv_newmortal() call will initialize the return value to undef, making that
 the default return value.
 
-     void
+     SV *
      rpcb_gettime(host)
           char *  host
 	  PREINIT:
@@ -590,7 +604,7 @@ the default return value.
 The next example demonstrates how one would place an explicit undef in the
 return value, should the need arise.
 
-     void
+     SV *
      rpcb_gettime(host)
           char *  host
 	  PREINIT:
@@ -1102,7 +1116,7 @@ File C<RPC.xs>: Interface to some ONC+ RPC bind library functions.
 
      MODULE = RPC  PACKAGE = RPC
 
-     void
+     SV *
      rpcb_gettime(host="localhost")
           char *host
 	  PREINIT: