document bareword prototype incompatibility

p4raw-id: //depot/perl@4862

2 files changed, 21 insertions, 3 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 04c16a5dae..f99aa3c97f 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -149,6 +149,14 @@ needs to be written with additional parentheses now:
 
 The behavior remains unaffected when C<not> is not followed by parentheses.
 
+=item Semantics of bareword prototype C<(*)> have changed
+
+Arguments prototyped as C<*> will now be visible within the subroutine
+as either a simple scalar or as a reference to a typeglob.  Perl 5.005
+always coerced simple scalar arguments to a typeglob, which wasn't useful
+in situations where the subroutine must distinguish between a simple
+scalar and a typeglob.  See L<perlsub/Prototypes>.
+
 =back
 
 =head2 C Source Incompatibilities
diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 416763f6d8..4ec11f99d4 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -928,11 +928,21 @@ Unbackslashed prototype characters have special meanings.  Any
 unbackslashed C<@> or C<%> eats all remaining arguments, and forces
 list context.  An argument represented by C<$> forces scalar context.  An
 C<&> requires an anonymous subroutine, which, if passed as the first
-argument, does not require the C<sub> keyword or a subsequent comma.  A
-C<*> allows the subroutine to accept a bareword, constant, scalar expression,
+argument, does not require the C<sub> keyword or a subsequent comma.
+
+A C<*> allows the subroutine to accept a bareword, constant, scalar expression,
 typeglob, or a reference to a typeglob in that slot.  The value will be
 available to the subroutine either as a simple scalar, or (in the latter
-two cases) as a reference to the typeglob.
+two cases) as a reference to the typeglob.  If you wish to always convert
+such arguments to a typeglob reference, use Symbol::qualify_to_ref() as
+follows:
+
+    use Symbol 'qualify_to_ref';
+
+    sub foo (*) {
+	my $fh = qualify_to_ref(shift, caller);
+	...
+    }
 
 A semicolon separates mandatory arguments from optional arguments.
 It is redundant before C<@> or C<%>, which gobble up everything else.