document that injecting newlines doesn't work

diff --git a/Changes b/Changes
index 73bbcc0..cab43f9 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1,5 +1,6 @@
 Changes for Devel-Declare
 
+  - Document that injecting newlines doesn't work.
   - Fix a C declaration after statement, which broke compatibility with
     older compilers (Jan Dubois).
   - Partially work around unexported core symbols affecting Perl 5.8 on

diff --git a/lib/Devel/Declare.pm b/lib/Devel/Declare.pm
index ea3b47e..923453d 100644 (file)
--- a/lib/Devel/Declare.pm
+++ b/lib/Devel/Declare.pm
@@ -471,6 +471,10 @@ This builtin returns the full text of the current line of the source document.
 =head4 C<set_linestr>
 
 This builtin sets the full text of the current line of the source document.
+Beware that injecting a newline into the middle of the line is likely
+to fail in surprising ways.  Generally, Perl's parser can rely on the
+`current line' actually being only a single line.  Use other kinds of
+whitespace instead, in the code that you inject.
 
 =head3 C<skipspace>