Document the "Unicode in package/sub names" problem;

a microfix in toke.c towards the final goal (the fix
removes the need to have quotes around Unicode package
names when calling a method on them)

p4raw-id: //depot/perl@17286

4 files changed, 34 insertions, 3 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index e6a4fe38d3..67806a92c1 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -3284,6 +3284,19 @@ In case of failure please try running them manually, for example
 
     ./perl -Ilib ext/Time/HiRes/HiRes.t
 
+=head2 Unicode in package/class and subroutine names does not work
+
+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.
+
 =head2 UNICOS/mk
 
 =over 4
diff --git a/pod/perltodo.pod b/pod/perltodo.pod
index 0e5d8a74ef..5f9a6cf2d0 100644
--- a/pod/perltodo.pod
+++ b/pod/perltodo.pod
@@ -98,7 +98,25 @@ UTF-8 identifier names should probably be canonicalized: NFC?
 
 UTF-8 in package names and sub names?  The first is problematic
 because of the mapping to pathnames, ditto for the second one if
-one does autosplitting, for example.
+one does autosplitting, for example.  Some of this works already
+in 5.8.0, but essentially it is unsupported.  Constructs to consider,
+at the very least:
+
+	use utf8;
+	package UnicodePackage;
+	sub new { bless {}, shift };
+	sub UnicodeMethod1 { ... $_[0]->UnicodeMethod2(...) ... }
+	sub UnicodeMethod2 { ... } # in here caller(0) should contain Unicode
+	...
+	package main;
+	my $x = UnicodePackage->new;
+	print ref $x, "\n";  # should be Unicode
+	$x->UnicodeMethod1(...);
+	my $y = UnicodeMethod3 UnicodePackage ...;
+
+In the above all I<UnicodeXxx> contain (identifier-worthy) characters
+beyond the code point 255, for example 256.  Wherever package/class or
+subroutine names can be returned needs to be checked for Unicodeness.
 
 =back
 
diff --git a/pod/perlunicode.pod b/pod/perlunicode.pod
index 25d512e70e..0aec6fee11 100644
--- a/pod/perlunicode.pod
+++ b/pod/perlunicode.pod
@@ -37,7 +37,7 @@ included to enable recognition of UTF-8 in the Perl scripts themselves
 (in string or regular expression literals, or in identifier names) on
 ASCII-based machines or to recognize UTF-EBCDIC on EBCDIC-based
 machines.  B<These are the only times when an explicit C<use utf8>
-is needed.>
+is needed.>  See L<utf8>.
 
 You can also use the C<encoding> pragma to change the default encoding
 of the data in your script; see L<encoding>.
diff --git a/pod/perluniintro.pod b/pod/perluniintro.pod
index 1468ae3282..cc11dde928 100644
--- a/pod/perluniintro.pod
+++ b/pod/perluniintro.pod
@@ -132,7 +132,7 @@ operations.  Only one case remains where an explicit C<use utf8> is
 needed: if your Perl script itself is encoded in UTF-8, you can use
 UTF-8 in your identifier names, and in string and regular expression
 literals, by saying C<use utf8>.  This is not the default because
-scripts with legacy 8-bit data in them would break.
+scripts with legacy 8-bit data in them would break.  See L<utf8>.
 
 =head2 Perl's Unicode Model