RT#132744: clarify subs/vars documentation

That ticket points out that subs.pm mentions using declared sub names
"without parentheses". That is indeed misleading; using the term "list
operators" would be better.

While changing that, I've also tweaked the wording about lexical scopes and
the inability to rescind these declarations, and ensured that the vars.pm
has the same revised text.

2 files changed, 14 insertions, 12 deletions

diff --git a/lib/subs.pm b/lib/subs.pm
index 10d6e023f4..24814596ba 100644
--- a/lib/subs.pm
+++ b/lib/subs.pm
@@ -1,10 +1,10 @@
 package subs;
 
-our $VERSION = '1.02';
+our $VERSION = '1.03';
 
 =head1 NAME
 
-subs - Perl pragma to predeclare sub names
+subs - Perl pragma to predeclare subroutine names
 
 =head1 SYNOPSIS
 
@@ -13,13 +13,14 @@ subs - Perl pragma to predeclare sub names
 
 =head1 DESCRIPTION
 
-This will predeclare all the subroutine whose names are 
-in the list, allowing you to use them without parentheses
+This will predeclare all the subroutines whose names are
+in the list, allowing you to use them without parentheses (as list operators)
 even before they're declared.
 
 Unlike pragmas that affect the C<$^H> hints variable, the C<use vars> and
-C<use subs> declarations are not BLOCK-scoped.  They are thus effective
-for the entire package in which they appear.  You may not rescind such
+C<use subs> declarations are not lexically scoped to the block they appear
+in: they affect
+the entire package in which they appear.  It is not possible to rescind these
 declarations with C<no vars> or C<no subs>.
 
 See L<perlmodlib/Pragmatic Modules> and L<strict/strict subs>.
diff --git a/lib/vars.pm b/lib/vars.pm
index 6ca6bb4d2c..5f6c0598ca 100644
--- a/lib/vars.pm
+++ b/lib/vars.pm
@@ -2,7 +2,7 @@ package vars;
 
 use 5.006;
 
-our $VERSION = '1.03';
+our $VERSION = '1.04';
 
 use warnings::register;
 use strict qw(vars subs);
@@ -61,13 +61,14 @@ functionality provided by this pragma has been superseded by C<our>
 declarations, available in Perl v5.6.0 or later, and use of this pragma is
 discouraged.  See L<perlfunc/our>.
 
-This will predeclare all the variables whose names are 
-in the list, allowing you to use them under "use strict", and
-disabling any typo warnings.
+This pragma will predeclare all the variables whose names are
+in the list, allowing you to use them under C<use strict>, and
+disabling any typo warnings for them.
 
 Unlike pragmas that affect the C<$^H> hints variable, the C<use vars> and
-C<use subs> declarations are not BLOCK-scoped.  They are thus effective
-for the entire file in which they appear.  You may not rescind such
+C<use subs> declarations are not lexically scoped to the block they appear
+in: they affect
+the entire package in which they appear.  It is not possible to rescind these
 declarations with C<no vars> or C<no subs>.
 
 Packages such as the B<AutoLoader> and B<SelfLoader> that delay