document deprecation of ' as the package separator

3 files changed, 19 insertions, 7 deletions

diff --git a/pod/perldata.pod b/pod/perldata.pod
index 27f6092f6f..0cf8eb22a3 100644
--- a/pod/perldata.pod
+++ b/pod/perldata.pod
@@ -21,8 +21,8 @@ structure it refers.  The rest of the name tells you the particular
 value to which it refers.  Usually this name is a single I<identifier>,
 that is, a string beginning with a letter or underscore, and
 containing letters, underscores, and digits.  In some cases, it may
-be a chain of identifiers, separated by C<::> (or by the slightly
-archaic C<'>); all but the last are interpreted as names of packages,
+be a chain of identifiers, separated by C<::> (or by the deprecated C<'>);
+all but the last are interpreted as names of packages,
 to locate the namespace in which to look up the final identifier
 (see L<perlmod/Packages> for details).  For a more in-depth discussion
 on identifiers, see L</Identifier parsing>.  It's possible to
@@ -137,11 +137,12 @@ That is, any word character in the ASCII range, as long as the first
 character is not a digit.
 
 There are two package separators in Perl: A double colon (C<::>) and a single
-quote (C<'>).  Normal identifiers can start or end with a double colon, and
-can contain several parts delimited by double colons.
-Single quotes have similar rules, but with the exception that they are not
-legal at the end of an identifier: That is, C<$'foo> and C<$foo'bar> are
-legal, but C<$foo'bar'> is not.
+quote (C<'>).  Use of C<'> as the package separator is deprecated and will be
+removed in Perl 5.40.  Normal identifiers can start or end with a double
+colon, and can contain several parts delimited by double colons.  Single
+quotes have similar rules, but with the exception that they are not legal at
+the end of an identifier: That is, C<$'foo> and C<$foo'bar> are legal, but
+C<$foo'bar'> is not.
 
 Additionally, if the identifier is preceded by a sigil --
 that is, if the identifier is part of a variable name -- it
diff --git a/pod/perldeprecation.pod b/pod/perldeprecation.pod
index 41dac866ef..b64ade3b5c 100644
--- a/pod/perldeprecation.pod
+++ b/pod/perldeprecation.pod
@@ -37,6 +37,14 @@ disabled I<even if you had previously written> C<use strict>. This was not
 the previous behaviour of C<use VERSION>, which at present will track
 explicitly-enabled strictness flags independently.
 
+=head3 Use of C<'> as a global name separator.
+
+Perl allows use of C<'> instead of C<::> to replace the parts of a
+package or global variable name, for example C<A::B> and C<A'B> are
+equivalent.
+
+C<'> will no longer be recognized as a name separator in Perl 5.40.
+
 =head2 Perl 5.38
 
 =head3 Pod::Html utility functions
diff --git a/pod/perlmod.pod b/pod/perlmod.pod
index 5c68273820..fa18872e6c 100644
--- a/pod/perlmod.pod
+++ b/pod/perlmod.pod
@@ -81,6 +81,9 @@ the $s variable in package C<owner>, which is probably not what you meant.
 Use braces to disambiguate, as in C<"This is ${owner}'s house">.
 X<::> X<'>
 
+Using C<'> as a package separator is deprecated and will be removed in
+Perl 5.40.
+
 Packages may themselves contain package separators, as in
 C<$OUTER::INNER::var>.  This implies nothing about the order of
 name lookups, however.  There are no relative packages: all symbols