X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2Futf8.pm;h=b18a043f10d31fd4e7eec31b42d16e313c4b4375;hb=13a6c0e08df522ae430c77e8a15932642751b605;hp=7b1ef0ddc4ab14762bb86f5371e77d3843505a8c;hpb=f1e62f77e429d3d8456955e82037ca65bbe65d82;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/lib/utf8.pm b/lib/utf8.pm
index 7b1ef0d..b18a043 100644
--- a/lib/utf8.pm
+++ b/lib/utf8.pm
@@ -79,21 +79,27 @@ The following functions are defined in the C<utf8::> package by the perl core.
 
 Converts internal representation of string to the Perl's internal
 I<UTF-X> form.  Returns the number of octets necessary to represent
-the string as I<UTF-X>.
+the string as I<UTF-X>.  Note that this should not be used to convert
+a legacy byte encoding to Unicode: use Encode for that.  Affected
+by the encoding pragma.
 
 =item * utf8::downgrade($string[, CHECK])
 
 Converts internal representation of string to be un-encoded bytes.
+Note that this should not be used to convert Unicode back to a legacy
+byte encoding: use Encode for that.  B<Not> affected by the encoding
+pragma.
 
 =item * utf8::encode($string)
 
-Converts (in-place) I<$string> from logical characters to octet sequence
-representing it in Perl's I<UTF-X> encoding.
-
-=item * $flag = utf8::decode($string)
+Converts (in-place) I<$string> from logical characters to octet
+sequence representing it in Perl's I<UTF-X> encoding.  Note that this
+should not be used to convert a legacy byte encoding to Unicode: use
+Encode for that.  =item * $flag = utf8::decode($string)
 
 Attempts to convert I<$string> in-place from Perl's I<UTF-X> encoding
-into logical characters.
+into logical characters.  Note that this should not be used to convert
+Unicode back to a legacy byte encoding: use Encode for that.
 
 =back