Underline that the current implementation is not

guaranteed to be forever; and reformat a bit.

p4raw-id: //depot/perl@15766

1 files changed, 15 insertions, 14 deletions

diff --git a/lib/utf8.pm b/lib/utf8.pm
index 2f32fd456b..c748a4993f 100644
--- a/lib/utf8.pm
+++ b/lib/utf8.pm
@@ -88,9 +88,9 @@ by the encoding pragma.
 
 =item * utf8::downgrade($string[, FAIL_OK])
 
-Converts (in-place) internal representation of string to be un-encoded bytes.
-Returns true on success. On failure dies or, if the value of
-FAIL_OK is true, returns false. Can be used to make sure that the
+Converts (in-place) internal representation of string to be un-encoded
+bytes.  Returns true on success. On failure dies or, if the value of
+FAIL_OK is true, returns false.  Can be used to make sure that the
 UTF-8 flag is off, e.g. when you want to make sure that the substr()
 or length() function works with the usually faster byte algorithm.
 Note that this should not be used to convert Unicode back to a legacy
@@ -101,15 +101,15 @@ pragma.
 
 Converts (in-place) I<$string> from logical characters to octet
 sequence representing it in Perl's I<UTF-X> encoding. Same as
-Encode::encode_utf8(). Note that this
-should not be used to convert a legacy byte encoding to Unicode: use
-Encode for that.
+Encode::encode_utf8(). 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. Same as Encode::decode_utf8(). Note that this should not be used to convert
-Unicode back to a legacy byte encoding: use Encode for that.
+into logical characters. Same as Encode::decode_utf8(). Note that this
+should not be used to convert Unicode back to a legacy byte encoding:
+use Encode for that.
 
 =item * $flag = utf8::valid(STRING)
 
@@ -121,14 +121,15 @@ state.
 
 =back
 
-C<utf8::encode> is like C<utf8::upgrade>, but the UTF8 flag is cleared.
-See L<perlunicode> for more on the UTF8 flag and the C API functions
-C<sv_utf8_upgrade>, C<sv_utf8_downgrade>, C<sv_utf8_encode>,
+C<utf8::encode> is like C<utf8::upgrade>, but the UTF8 flag is
+cleared.  See L<perlunicode> for more on the UTF8 flag and the C API
+functions C<sv_utf8_upgrade>, C<sv_utf8_downgrade>, C<sv_utf8_encode>,
 and C<sv_utf8_decode>, which are wrapped by the Perl functions
 C<utf8::upgrade>, C<utf8::downgrade>, C<utf8::encode> and
-C<utf8::decode>. The functions utf8::valid, utf8::encode,
-utf8::decode, utf8::upgrade, and utf8::downgrade are always available,
-without a C<require utf8> statement.
+C<utf8::decode>.  Note that in the Perl 5.8.0 implementation the
+functions utf8::valid, utf8::encode, utf8::decode, utf8::upgrade,
+and utf8::downgrade are always available, without a C<require utf8>
+statement-- this may change in future releases.
 
 =head1 SEE ALSO