1 files changed, 43 insertions, 22 deletions

diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 24b16128dd..e0a23b0162 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -16,8 +16,8 @@ desperation):
     (A) An alien error message (not generated by Perl).
 
 Optional warnings are enabled by using the B<-w> switch.  Warnings may
-be captured by setting C<$SIG{__WARN__}> to a reference to a routine that will be
-called on each warning instead of printing it.  See L<perlvar>.
+be captured by setting C<$SIG{__WARN__}> to a reference to a routine that
+will be called on each warning instead of printing it.  See L<perlvar>.
 Trappable errors may be trapped using the eval operator.  See
 L<perlfunc/eval>.
 
@@ -339,6 +339,14 @@ Perl yourself.
 (F) An untrapped exception was raised while executing a BEGIN subroutine.
 Compilation stops immediately and the interpreter is exited.
 
+=item BEGIN not safe after errors--compilation aborted
+
+(F) Perl found a C<BEGIN {}> subroutine (or a C<use> directive, which
+implies a C<BEGIN {}>) after one or more compilation errors had
+already occurred.  Since the intended environment for the C<BEGIN {}>
+could not be guaranteed (due to the errors), and since subsequent code
+likely depends on its correct operation, Perl just gave up.
+
 =item bind() on closed fd
 
 (W) You tried to do a bind on a closed socket.  Did you forget to check
@@ -646,7 +654,7 @@ buffer.
 
 =item Can't open %s: %s
 
-(S) An inplace edit couldn't open the original file for the indicated reason.
+(S) An in-place edit couldn't open the original file for the indicated reason.
 Usually this is because you don't have read permission for the file.
 
 =item Can't open bidirectional pipe
@@ -1066,8 +1074,8 @@ the line, and you really meant a "less than".
 
 =item Global symbol "%s" requires explicit package name
 
-(F) You've said "use strict vars", which indicates that all variables must
-either be lexically scoped (using "my"), or explicitly qualified to
+(F) You've said "use strict vars", which indicates that all variables
+must either be lexically scoped (using "my"), or explicitly qualified to
 say which package the global variable is in (using "::").
 
 =item goto must have label
@@ -1099,8 +1107,20 @@ or it may indicate that a logical name table has been corrupted.
 
 (F) A carriage return character was found in the input.  This is an
 error, and not a warning, because carriage return characters can break
-here documents (e.g. C<print E<lt>E<lt>EOF;>).  Note that Perl always
-opens scripts in text mode, so this error should only occur in C<eval>.
+here documents (e.g., C<print E<lt>E<lt>EOF;>).
+  
+Under UNIX, this error is usually caused by executing Perl code --
+either the main program, a module, or an eval'd string -- that was
+transferred over a network connection from a non-UNIX system without
+properly converting the text file format.
+
+Under systems that use something other than '\n' to delimit lines of
+text, this error can also be caused by reading Perl code from a file
+handle that is in binary mode (as set by the C<binmode> operator).
+
+In either case, the Perl code in question will probably need to be
+converted with something like C<s/\x0D\x0A?/\n/g> before it can be
+executed.
 
 =item Illegal division by zero
 
@@ -1301,10 +1321,10 @@ like C<$foo[1][2][3]>, as in C.
 
 =item Name "%s::%s" used only once: possible typo
 
-(W) Typographical errors often show up as unique variable names.  If you
-had a good reason for having a unique name, then just mention it
-again somehow to suppress the message (the C<use vars> pragma is
-provided for just this purpose).
+(W) Typographical errors often show up as unique variable names.
+If you had a good reason for having a unique name, then just mention
+it again somehow to suppress the message.  The C<use vars> pragma is
+provided for just this purpose.
 
 =item Negative length
 
@@ -1796,7 +1816,7 @@ old-fashioned way, with quotes and commas:
 =item Possible attempt to separate words with commas
 
 (W) qw() lists contain items separated by whitespace; therefore commas
-aren't needed to separate the items. (You may have used different
+aren't needed to separate the items.  (You may have used different
 delimiters than the parentheses shown here; braces are also frequently
 used.)
 
@@ -1826,9 +1846,10 @@ is now misinterpreted as
 
     open(FOO || die);
 
-because of the strict regularization of Perl 5's grammar into unary and
-list operators.  (The old open was a little of both.) You must put
-parentheses around the filehandle, or use the new "or" operator instead of "||".
+because of the strict regularization of Perl 5's grammar into unary
+and list operators.  (The old open was a little of both.)  You must
+put parentheses around the filehandle, or use the new "or" operator
+instead of "||".
 
 =item print on closed filehandle %s
 
@@ -2104,7 +2125,7 @@ may break this.
 
 (P) The substitution was looping infinitely.  (Obviously, a
 substitution shouldn't iterate more times than there are characters of
-input, which is what happened.) See the discussion of substitution in
+input, which is what happened.)  See the discussion of substitution in
 L<perlop/"Quote and Quote-like Operators">.
 
 =item Substitution pattern not terminated
@@ -2490,13 +2511,13 @@ L<perlref> for more on this.
 (W) A copy of the object returned from C<tie> (or C<tied>) was still
 valid when C<untie> was called.
 
-=item Value of %s construct can be "0"; test with defined()
+=item Value of %s can be "0"; test with defined()
 
-(W) In a conditional expression, you used <HANDLE>, <*> (glob), or
-C<readdir> as a boolean value.  Each of these constructs can return a
-value of "0"; that would make the conditional expression false, which
-is probably not what you intended.  When using these constructs in
-conditional expressions, test their values with the C<defined> operator.
+(W) In a conditional expression, you used <HANDLE>, <*> (glob), C<each()>,
+or C<readdir()> as a boolean value.  Each of these constructs can return a
+value of "0"; that would make the conditional expression false, which is
+probably not what you intended.  When using these constructs in conditional
+expressions, test their values with the C<defined> operator.
 
 =item Variable "%s" is not imported%s