threads::shared::queue and semaphore become Thread::Semaphore

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

diff --git a/lib/utf8.pm b/lib/utf8.pm
index 2f32fd4..5a37aec 100644 (file)
--- a/lib/utf8.pm
+++ b/lib/utf8.pm
@@ -56,10 +56,11 @@ Enabling the C<utf8> pragma has the following effect:
 
 Bytes in the source text that have their high-bit set will be treated
 as being part of a literal UTF-8 character.  This includes most
-literals such as identifiers, string constants, constant regular
-expression patterns and package names.  On EBCDIC platforms characters
-in the Latin 1 character set are treated as being part of a literal
-UTF-EBCDIC character.
+literals such as identifier names, string constants, and constant
+regular expression patterns.
+
+On EBCDIC platforms characters in the Latin 1 character set are
+treated as being part of a literal UTF-EBCDIC character.
 
 =back
 
@@ -88,9 +89,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 +102,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 +122,28 @@ 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 BUGS
+
+One can have Unicode in identifier names, but not in package/class or
+subroutine names.  While some limited functionality towards this does
+exist as of Perl 5.8.0, that is more accidental than designed; use of
+Unicode for the said purposes is unsupported.
+
+One reason of this unfinishedness is its (currently) inherent
+unportability: since both package names and subroutine names may need
+to be mapped to file and directory names, the Unicode capability of
+the filesystem becomes important-- and there unfortunately aren't
+portable answers.
 
 =head1 SEE ALSO