X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperldebug.pod;h=01f35e1eb443763e298125887c42e649f10651db;hb=7817ba4dfeb754838a0da8f159127895c2dcf4fc;hp=5b7a2bdbb0e737664b706359818e06c99d002313;hpb=055fd3a96a4b067d75446c3d47ffc318e9acc40d;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perldebug.pod b/pod/perldebug.pod
index 5b7a2bd..01f35e1 100644
--- a/pod/perldebug.pod
+++ b/pod/perldebug.pod
@@ -68,7 +68,7 @@ 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
+because this is just Perl's own C<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
@@ -82,7 +82,7 @@ recursively, unlike the real C<print> function in Perl.
 See L<Dumpvalue> if you'd like to do this yourself.
 
 The output format is governed by multiple options described under
-L<"Options">.
+L<"Configurable Options">.
 
 =item V [pkg [vars]]
 
@@ -211,7 +211,7 @@ breakpoint on the line about to be executed.  If a condition
 is specified, it's evaluated each time the statement is reached: a
 breakpoint is taken only if the condition is true.  Breakpoints may
 only be set on lines that begin an executable statement.  Conditions
-don't use B<if>:
+don't use C<if>:
 
     b 237 $x > 30
     b 237 ++$count237 < 11
@@ -308,8 +308,8 @@ For historical reasons, the C<=value> is optional, but defaults to
 1 only where it is safe to do so--that is, mostly for Boolean
 options.  It is always better to assign a specific value using C<=>.
 The C<option> can be abbreviated, but for clarity probably should
-not be.  Several options can be set together.  See L<"Options"> for
-a list of these.
+not be.  Several options can be set together.  See L<"Configurable Options"> 
+for a list of these.
 
 =item < ? 
 
@@ -342,7 +342,7 @@ missing, all actions are wiped out!
 
 Adds an action (Perl command) to happen after the prompt when you've
 just given a command to return to executing the script.  A multi-line
-command may be entered by slackbashing the newlines.
+command may be entered by backslashing the newlines.
 
 =item { ?
 
@@ -416,7 +416,7 @@ Run the debugger command, piping DB::OUT into your current pager.
 
 =item ||dbcmd
 
-Same as C<|dbcmd> but DB::OUT is temporarily B<select>ed as well.
+Same as C<|dbcmd> but DB::OUT is temporarily C<select>ed as well.
 
 =item = [alias value]
 
@@ -488,16 +488,23 @@ Run Tk while prompting (with ReadLine).
 
 =item C<signalLevel>, C<warnLevel>, C<dieLevel>
 
-Level of verbosity.  By default, the debugger prints backtraces
-upon receiving any kind of warning (this is often annoying) and
-fatal exceptions (this is often valuable).  It will attempt to print
-a message when uncaught INT, BUS, or SEGV signals arrive.
-
-To disable this behaviour, set these values to 0.  If C<dieLevel>
-is 2, the debugger usurps your own exception handler and prints out
-a trace of these, replacing your exceptions with its own.  This may
-be useful for some tracing purposes, but tends to hopelessly destroy
-any program that takes its exception handling seriously.
+Level of verbosity.  By default, the debugger leaves your exceptions
+and warnings alone, because altering them can break correctly running
+programs.  It will attempt to print a message when uncaught INT, BUS, or
+SEGV signals arrive.  (But see the mention of signals in L<BUGS> below.)
+
+To disable this default safe mode, set these values to something higher
+than 0.  At a level of 1, you get backtraces upon receiving any kind
+of warning (this is often annoying) or exception (this is
+often valuable).  Unfortunately, the debugger cannot discern fatal
+exceptions from non-fatal ones.  If C<dieLevel> is even 1, then your
+non-fatal exceptions are also traced and unceremoniously altered if they
+came from C<eval'd> strings or from any kind of C<eval> within modules
+you're attempting to load.  If C<dieLevel> is 2, the debugger doesn't
+care where they came from:  It usurps your exception handler and prints
+out a trace, then modifies all exceptions with its own embellishments.
+This may perhaps be useful for some tracing purposes, but tends to hopelessly
+destroy any program that takes its exception handling seriously.
 
 =item C<AutoTrace>
 
@@ -620,7 +627,7 @@ specified in the C<TTY> option at startup, or to a tty found at
 runtime using the C<Term::Rendezvous> module of your choice.
 
 This module should implement a method named C<new> that returns an object
-with two methods: C<IN> and C<OUT.  These should return filehandles to use
+with two methods: C<IN> and C<OUT>.  These should return filehandles to use
 for debugging input and output correspondingly.  The C<new> method should
 inspect an argument containing the value of C<$ENV{PERLDB_NOTTY}> at
 startup, or C<"/tmp/perldbtty$$"> otherwise.  This file is not 
@@ -760,6 +767,11 @@ Breakable lines are marked with C<:>.  Lines with breakpoints are
 marked by C<b> and those with actions by C<a>.  The line that's
 about to be executed is marked by C<< ==> >>.
 
+Please be aware that code in debugger listings may not look the same
+as your original source code.  Line directives and external source
+filters can alter the code before Perl sees it, causing code to move
+from its original positions or take on entirely different forms.
+
 =item Frame listing
 
 When the C<frame> option is set, the debugger would print entered (and
@@ -927,5 +939,14 @@ L<perlrun>.
 You cannot get stack frame information or in any fashion debug functions
 that were not compiled by Perl, such as those from C or C++ extensions.
 
-If you alter your @_ arguments in a subroutine (such as with B<shift>
-or B<pop>, the stack backtrace will not show the original values.
+If you alter your @_ arguments in a subroutine (such as with C<shift>
+or C<pop>, the stack backtrace will not show the original values.
+
+The debugger does not currently work in conjunction with the B<-W>
+command-line switch, because it itself is not free of warnings.
+
+If you're in a slow syscall (like C<wait>ing, C<accept>ing, or C<read>ing
+from your keyboard or a socket) and haven't set up your own C<$SIG{INT}>
+handler, then you won't be able to CTRL-C your way back to the debugger,
+because the debugger's own C<$SIG{INT}> handler doesn't understand that
+it needs to raise an exception to longjmp(3) out of slow syscalls.