clarify gotcha with #line directives (from Rocco Caputo

<troc@netrus.net>)

p4raw-id: //depot/perl@6123

2 files changed, 10 insertions, 0 deletions

diff --git a/pod/perldebug.pod b/pod/perldebug.pod
index c8ef60fa45..bccdcf4f51 100644
--- a/pod/perldebug.pod
+++ b/pod/perldebug.pod
@@ -767,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
diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index dfded2ecde..a65b4cd263 100644
--- a/pod/perlsyn.pod
+++ b/pod/perlsyn.pod
@@ -598,6 +598,11 @@ C</^#\s*line\s+(\d+)\s*(?:\s"([^"]+)")?\s*$/> with C<$1> being the line
 number for the next line, and C<$2> being the optional filename
 (specified within quotes).
 
+There is a fairly obvious gotcha included with the line directive:
+Debuggers and profilers will only show the last source line to appear
+at a particular line number in a given file.  Care should be taken not
+to cause line number collisions in code you'd like to debug later.
+
 Here are some examples that you should be able to type into your command
 shell: