integrate cfgperl contents into mainline

p4raw-id: //depot/perl@3516

4 files changed, 32 insertions, 16 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 5b4eb10553..9408d32c9d 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -473,6 +473,18 @@ by Perl.
 (W) You used the C<open(FH, "| command")> or C<open(FH, "command |")>
 construction, but the command was missing or blank.
 
+=item defined(@array) is deprecated (and not really meaningful)
+
+(D) defined() is not usually useful on arrays because it checks for an
+undefined I<scalar> value.  If you want to see if the array is empty,
+just use C<if (@array) { # not empty }> for example.  
+
+=item defined(%hash) is deprecated (and not really meaningful)
+
+(D) defined() is not usually useful on hashes because it checks for an
+undefined I<scalar> value.  If you want to see if the hash is empty,
+just use C<if (%hash) { # not empty }> for example.  
+
 =head1 Obsolete Diagnostics
 
 Todo.
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 688e847085..0084f9c6da 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -1105,6 +1105,18 @@ times more than it has returned.  This probably indicates an infinite
 recursion, unless you're writing strange benchmark programs, in which
 case it indicates something else.
 
+=item defined(@array) is deprecated (and not really meaningful)
+
+(D) defined() is not usually useful on arrays because it checks for an
+undefined I<scalar> value.  If you want to see if the array is empty,
+just use C<if (@array) { # not empty }> for example.  
+
+=item defined(%hash) is deprecated (and not really meaningful)
+
+(D) defined() is not usually useful on hashes because it checks for an
+undefined I<scalar> value.  If you want to see if the hash is empty,
+just use C<if (%hash) { # not empty }> for example.  
+
 =item Delimiter for here document is too long
 
 (F) In a here document construct like C<E<lt>E<lt>FOO>, the label
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index ed3de62a23..4043301a5e 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -912,24 +912,14 @@ should use C<defined> only when you're questioning the integrity of what
 you're trying to do.  At other times, a simple comparison to C<0> or C<""> is
 what you want.
 
-Currently, using C<defined> on an entire array or hash reports whether
-memory for that aggregate has ever been allocated.  So an array you set
-to the empty list appears undefined initially, and one that once was full
-and that you then set to the empty list still appears defined.  You
-should instead use a simple test for size:
+Use of C<defined> on aggregates (hashes and arrays) is deprecated.  It
+used to report whether memory for that aggregate has ever been
+allocated.  This behavior may disappear in future versions of Perl.
+You should instead use a simple test for size:
 
     if (@an_array) { print "has array elements\n" }
     if (%a_hash)   { print "has hash members\n"   }
 
-Using C<undef> on these, however, does clear their memory and then report
-them as not defined anymore, but you shouldn't do that unless you don't
-plan to use them again, because it saves time when you load them up
-again to have memory already ready to be filled.  The normal way to 
-free up space used by an aggregate is to assign the empty list.
-
-This counterintuitive behavior of C<defined> on aggregates may be
-changed, fixed, or broken in a future release of Perl.
-
 See also L</undef>, L</exists>, L</ref>.
 
 =item delete EXPR
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index cb41c96aa0..9402608daf 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -220,8 +220,10 @@ to change that.  An explicit close on a filehandle resets the line
 number.  Because C<E<lt>E<gt>> never does an explicit close, line
 numbers increase across ARGV files (but see examples in L<perlfunc/eof>).
 Consider this variable read-only: setting it does not reposition
-the seek pointer; you'll have to do that on your own.  (Mnemonic:
-many programs use "." to mean the current line number.)  
+the seek pointer; you'll have to do that on your own.  Localizing C<$.>
+has the effect of also localizing Perl's notion of "the last read
+filehandle".  (Mnemonic: many programs use "." to mean the current line
+number.)
 
 =item input_record_separator HANDLE EXPR