Doc update for changes in 5.15.0 + tweaks

5 files changed, 39 insertions, 30 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 40c1f8a5f7..46f71d19fe 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -166,17 +166,21 @@ C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>
 
 =item Keywords related to the switch feature
 
-C<break>, C<continue>, C<default, >C<given>, C<when>
+C<break>, C<continue>, C<default>, C<given>, C<when>
 
-These are available only if you enable the C<"switch"> feature.
+Except for C<continue>, these are available only if you enable the
+C<"switch"> feature or use the C<CORE::> prefix.
 See L<feature> and L<perlsyn/"Switch statements">.  
-Alternately, include a C<use v5.10> or later to the current scope.
+Alternately, include a C<use v5.10> or later to the current scope.  In Perl
+5.14 and earlier, C<continue> required the C<"switch"> feature, like the
+other keywords.
 
 =item Keywords related to scoping
 
 C<caller>, C<import>, C<local>, C<my>, C<our>, C<package>, C<state>, C<use>
 
-C<state> is available only if the C<"state"> feature is enabled. See
+C<state> is available only if the C<"state"> feature
+is enabled or if it is prefixed with C<CORE::>. See
 L<feature>.  Alternately, include a C<use v5.10> or later to the current scope.
 
 =item Miscellaneous functions
@@ -646,7 +650,8 @@ See L<perlmod/"Perl Modules">.
 Break out of a C<given()> block.
 
 This keyword is enabled by the C<"switch"> feature: see
-L<feature> for more information.  Alternately, include a C<use
+L<feature> for more information.  You can also access it by
+prefixing it with C<CORE::>.  Alternately, include a C<use
 v5.10> or later to the current scope.
 
 =item caller EXPR
@@ -978,7 +983,8 @@ X<continue>
 
 =item continue
 
-C<continue> is actually a flow control statement rather than a function.  If
+When followed by a BLOCK, C<continue> is actually a
+flow control statement rather than a function.  If
 there is a C<continue> BLOCK attached to a BLOCK (typically in a C<while> or
 C<foreach>), it is always executed just before the conditional is about to
 be evaluated again, just like the third part of a C<for> loop in C.  Thus
@@ -1005,9 +1011,11 @@ Omitting the C<continue> section is equivalent to using an
 empty one, logically enough, so C<next> goes directly back
 to check the condition at the top of the loop.
 
-If the C<"switch"> feature is enabled, C<continue> is also a function that
+When there is no BLOCK, C<continue> is a function that
 falls through the current C<when> or C<default> block instead of iterating
 a dynamically enclosing C<foreach> or exiting a lexically enclosing C<given>.
+In Perl 5.14 and earlier, this form of C<continue> was
+only available when the C<"switch"> feature was enabled.
 See L<feature> and L<perlsyn/"Switch statements"> for more
 information.
 
@@ -1163,7 +1171,8 @@ Portability issues: L<perlport/dbmopen>.
 
 Within a C<foreach> or a C<given>, a C<default> BLOCK acts like a C<when>
 that's always true.  Only available after Perl 5.10, and only if the
-C<switch> feature has been requested.  See L</when>.
+C<switch> feature has been requested or if the keyword is prefixed with
+C<CORE::>.  See L</when>.
 
 =item defined EXPR
 X<defined> X<undef> X<undefined>
@@ -5340,7 +5349,8 @@ simply an abbreviation for C<{ local $\ = "\n"; print LIST }>.  To use
 FILEHANDLE without a LIST to print the contents of C<$_> to it, you must
 use a real filehandle like C<FH>, not an indirect one like C<$fh>.
 
-This keyword is available only when the C<"say"> feature is enabled; see
+This keyword is available only when the C<"say"> feature
+is enabled, or when prefixed with C<CORE::>; see
 L<feature>.  Alternately, include a C<use v5.10> or later to the current
 scope.
 
@@ -6722,13 +6732,14 @@ X<state>
 
 =item state TYPE EXPR : ATTRS
 
-C<state> declares a lexically scoped variable, just like C<my> does.
+C<state> declares a lexically scoped variable, just like C<my>.
 However, those variables will never be reinitialized, contrary to
 lexical variables that are reinitialized each time their enclosing block
 is entered.
 
 C<state> variables are enabled only when the C<use feature "state"> pragma 
-is in effect.  See L<feature>.
+is in effect, unless the keyword is written as C<CORE::state>.
+See L<feature>.
 
 =item study SCALAR
 X<study>
diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index db398dd723..01c525d069 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -439,10 +439,12 @@ if you want to stay compatible with releases older than 5.10.
 
 =head3 Persistent variables via state()
 
-Beginning with perl 5.9.4, you can declare variables with the C<state>
-keyword in place of C<my>. For that to work, though, you must have
+Beginning with Perl 5.9.4, you can declare variables with the C<state>
+keyword in place of C<my>.  For that to work, though, you must have
 enabled that feature beforehand, either by using the C<feature> pragma, or
-by using C<-E> on one-liners. (see L<feature>)
+by using C<-E> on one-liners (see L<feature>).  Beginning with Perl 5.16,
+you can also write it as C<CORE::state>, which does not require the
+C<feature> pragma.
 
 For example, the following code maintains a private counter, incremented
 each time the gimme_another() function is called:
@@ -740,8 +742,7 @@ To do this, you have to declare the subroutine to return an lvalue.
 
     my $val;
     sub canmod : lvalue {
-	# return $val; this doesn't work, don't say "return"
-	$val;
+	$val;  # or:  return $val;
     }
     sub nomod {
 	$val;
@@ -770,14 +771,9 @@ all the subroutines are called in a list context.
 
 =item Lvalue subroutines are EXPERIMENTAL
 
-They appear to be convenient, but there are several reasons to be
+They appear to be convenient, but there is at least one reason to be
 circumspect.
 
-You can't use the return keyword, you must pass out the value before
-falling out of subroutine scope. (see comment in example above).  This
-is usually not a problem, but it disallows an explicit return out of a
-deeply nested loop, which is sometimes a nice way out.
-
 They violate encapsulation.  A normal mutator can check the supplied
 argument before setting the attribute it is protecting, an lvalue
 subroutine never gets that chance.  Consider;
diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index a88fb036ba..a914f85ebf 100644
--- a/pod/perlsyn.pod
+++ b/pod/perlsyn.pod
@@ -530,7 +530,9 @@ Starting from Perl 5.10, you can say
     use feature "switch";
 
 which enables a switch feature that is closely based on the
-Perl 6 proposal.
+Perl 6 proposal.  Starting from Perl 5.16, one can prefix the switch
+keywords with C<CORE::> to access the feature without a C<use feature>
+statement.
 
 The keywords C<given> and C<when> are analogous
 to C<switch> and C<case> in other languages, so the code
diff --git a/pod/perltie.pod b/pod/perltie.pod
index 456cc60cba..887f2f02ed 100644
--- a/pod/perltie.pod
+++ b/pod/perltie.pod
@@ -870,11 +870,10 @@ program, where output to STDOUT and STDERR may have to be redirected
 in some special way.  See nvi and the Apache module for examples.
 
 When tying a handle, the first argument to C<tie> should begin with an
-asterisk. So, if you are tying STDOUT, use C<*STDOUT>. If you have assigned
-it to a scalar variable, say C<$handle>, use C<*$handle>. C<tie $handle>
-works, too, but that is considered a bug and will be fixed in Perl 5.16. It
-is supposed to tie the scalar C<$handle>, not the handle inside it.
-C<tie $handle> emits a deprecation warning as of Perl 5.14.
+asterisk.  So, if you are tying STDOUT, use C<*STDOUT>.  If you have
+assigned it to a scalar variable, say C<$handle>, use C<*$handle>.
+C<tie $handle> ties the scalar variable C<$handle>, not the handle inside
+it.
 
 In our example we're going to create a shouting handle.
 
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index ccc4196bfa..890909d526 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -185,8 +185,9 @@ Mnemonic: works in double-quoted context.
 =item $$
 X<$$> X<$PID> X<$PROCESS_ID>
 
-The process number of the Perl running this script. You should
-consider this variable read-only, although it will be altered
+The process number of the Perl running this script. Though you I<can> set
+this variable, doing so is generally discouraged, although it can be
+invaluable for some testing purposes. It will be reset automatically
 across C<fork()> calls.
 
 Note for Linux users: on Linux, the C functions C<getpid()> and