for File::Temp::tempdir(CLEANUP => 1)

[p5sagit/p5-mst-13.2.git] / lib / utf8.pm

diff --git a/lib/utf8.pm b/lib/utf8.pm
index 91f8a10..9039447 100644 (file)
--- a/lib/utf8.pm
+++ b/lib/utf8.pm
@@ -50,12 +50,19 @@ the source text as literal bytes in the current lexical scope.
 This pragma is primarily a compatibility device.  Perl versions
 earlier than 5.6 allowed arbitrary bytes in source code, whereas
 in future we would like to standardize on the UTF-8 encoding for
-source text.  Until UTF-8 becomes the default format for source
-text, this pragma should be used to recognize UTF-8 in the source.
-When UTF-8 becomes the standard source format, this pragma will
-effectively become a no-op.  For convenience in what follows the
-term I<UTF-X> is used to refer to UTF-8 on ASCII and ISO Latin based
-platforms and UTF-EBCDIC on EBCDIC based platforms.
+source text.
+
+B<Do not use this pragma for anything else than telling Perl that your
+script is written in UTF-8.> The utility functions described below are
+useful for their own purposes, but they are not really part of the
+"pragmatic" effect.
+
+Until UTF-8 becomes the default format for source text, either this
+pragma or the L</encoding> pragma should be used to recognize UTF-8
+in the source.  When UTF-8 becomes the standard source format, this
+pragma will effectively become a no-op.  For convenience in what
+follows the term I<UTF-X> is used to refer to UTF-8 on ASCII and ISO
+Latin based platforms and UTF-EBCDIC on EBCDIC based platforms.
 
 Enabling the C<utf8> pragma has the following effect:
 
@@ -79,11 +86,23 @@ will be unhappy since the bytes are most probably not well-formed
 UTF-8.  If you want to have such bytes and use utf8, you can disable
 utf8 until the end the block (or file, if at top level) by C<no utf8;>.
 
+If you want to automatically upgrade your 8-bit legacy bytes to UTF-8,
+use the L</encoding> pragma instead of this pragma.  For example, if
+you want to implicitly upgrade your ISO 8859-1 (Latin-1) bytes to UTF-8
+as used in e.g. C<chr()> and C<\x{...}>, try this:
+
+    use encoding "latin-1";
+    my $c = chr(0xc4);
+    my $x = "\x{c5}";
+
+In case you are wondering: yes, C<use encoding 'utf8';> works much
+the same as C<use utf8;>.
+
 =head2 Utility functions
 
 The following functions are defined in the C<utf8::> package by the
 Perl core.  You do not need to say C<use utf8> to use these and in fact
-you should not unless you really want to have UTF-8 source code.
+you should not say that  unless you really want to have UTF-8 source code.
 
 =over 4
 
@@ -165,6 +184,6 @@ portable answers.
 
 =head1 SEE ALSO
 
-L<perluniintro>, L<perlunicode>, L<bytes>
+L<perluniintro>, L<encoding>, L<perlunicode>, L<bytes>
 
 =cut