Clarification: use encoding cannot be used to

change the default encoding of "your whole script";
only the default encoding of the *data*.  Also, it
seems that "use encoding" does not mix with "use utf8"
(a coredumping recursion ensues).  Should not be a huge
problem since "use utf8" is pretty marginal nowadays.

p4raw-id: //depot/perl@12786

3 files changed, 10 insertions, 2 deletions

diff --git a/ext/Encode/Encode.pm b/ext/Encode/Encode.pm
index 19827db07d..863022b18f 100644
--- a/ext/Encode/Encode.pm
+++ b/ext/Encode/Encode.pm
@@ -868,7 +868,7 @@ More examples:
 See L<PerlIO> for more information.
 
 See also L<encoding> for how to change the default encoding of the
-script itself.
+data in your script.
 
 =head1 Encoding How to ...
 
diff --git a/lib/encoding.pm b/lib/encoding.pm
index 1c9838e7aa..e758687c59 100644
--- a/lib/encoding.pm
+++ b/lib/encoding.pm
@@ -47,6 +47,13 @@ affected by this pragma.  They probably should.
 
 Also chr(), ord(), and C<\N{...}> might become affected.
 
+=head1 KNOWN PROBLEMS
+
+Cannot be combined with C<use utf8>.  Note that this is a problem
+B<only> if you would like to have Unicode identifiers in your scripts.
+You should not need C<use utf8> for anything else these days
+(since Perl 5.8.0)
+
 =head1 SEE ALSO
 
 L<perlunicode>
diff --git a/pod/perlunicode.pod b/pod/perlunicode.pod
index 273cce0026..a5a69ff727 100644
--- a/pod/perlunicode.pod
+++ b/pod/perlunicode.pod
@@ -53,7 +53,8 @@ B<NOTE: this should be the only place where an explicit C<use utf8> is
 needed>.
 
 You can also use the C<encoding> pragma to change the default encoding
-of the whole script; see L<encoding>.
+of the data in your script; see L<encoding>.   Currently this cannot
+be combined with C<use utf8>.
 
 =back