Update perlfaq to CPAN version 5.0150036

  [DELTA]

  5.0150036 Sat 22 Oct 2011 16:20:34 +0100
    * Website moved from faq.perl.org -> learn.perl.org (ranguard)
    * Delete some questions/cleanup copy (ranguard)
    * Make perlfaq.pod shorter/cleaner (kablamo)
    * Many cleanups and corrections (shlomif)

10 files changed, 178 insertions, 193 deletions

diff --git a/cpan/perlfaq/lib/perlfaq.pm b/cpan/perlfaq/lib/perlfaq.pm
index 416a98873f..0b97525eb1 100644
--- a/cpan/perlfaq/lib/perlfaq.pm
+++ b/cpan/perlfaq/lib/perlfaq.pm
@@ -1,6 +1,6 @@
 package perlfaq;
 {
-  $perlfaq::VERSION = '5.0150035';
+  $perlfaq::VERSION = '5.0150036';
 }
 
 0; # not is it supposed to be loaded
diff --git a/cpan/perlfaq/lib/perlfaq.pod b/cpan/perlfaq/lib/perlfaq.pod
index 095c436270..ff269a3bb1 100644
--- a/cpan/perlfaq/lib/perlfaq.pod
+++ b/cpan/perlfaq/lib/perlfaq.pod
@@ -8,65 +8,41 @@ The perlfaq comprises several documents that answer the most commonly
 asked questions about Perl and Perl programming. It's divided by topic
 into nine major sections outlined in this document.
 
-=head2 Where to get the perlfaq
+=head2 Where to find the perlfaq
 
-The perlfaq comes with the standard Perl distribution, so if you have Perl
-you should have the perlfaq. You should also have the C<perldoc> tool
-that lets you read the L<perlfaq>:
+The perlfaq is an evolving document.  Read the latest version at
+L<http://learn.perl.org/faq/>.  It is also included in the standard Perl
+distribution.
 
-    $ perldoc perlfaq
-
-or search the perlfaq question headings:
+=head2 How to use the perlfaq
 
-    $ perldoc -q open
+The C<perldoc> command line tool is part of the standard Perl distribution. To
+read the perlfaq:
 
-See L<perldoc> for more information.
+    $ perldoc perlfaq
 
-Besides your local system, you can find the perlfaq on the web, including
-at L<http://perldoc.perl.org/>.
+To search the perlfaq question headings:
 
-The perlfaq is an evolving document and you can read the latest version
-at L<http://faq.perl.org/>.
+    $ perldoc -q open
 
 =head2 How to contribute to the perlfaq
 
-Please review L<https://github.com/perl-doc-cats/perlfaq/wiki>,
-if you do not find your suggestion please create an issue or pull request
-against L<https://github.com/perl-doc-cats/perlfaq>.
+Review L<https://github.com/perl-doc-cats/perlfaq/wiki>.  If you don't find
+your suggestion create an issue or pull request against
+L<https://github.com/perl-doc-cats/perlfaq>.
 
-Once approved they will then be merged into 
-L<https://github.com/tpf/perlfaq> which is the latest live version that
-drives L<http://faq.perl.org/> and will be distributed with the next
-release of Perl 5.
+Once approved, changes are merged into L<https://github.com/tpf/perlfaq>, the
+repository which drives L<http://learn.perl.org/faq/>, and they are 
+distributed with the next Perl 5 release.
 
 =head2 What if my question isn't answered in the FAQ?
 
-If you have a question that isn't in the FAQ and you would like help with
-it, try the resources in L<perlfaq2>.
-
-=head1 CREDITS
-
-Tom Christiansen wrote the original perlfaq then expanded it with the
-help of Nat Torkington. brian d foy substantialy edited and expanded
-the perlfaq. perlfaq-workers and others have also supplied feedback, 
-patches and corrections over the years.
-
-=head1 AUTHOR AND COPYRIGHT
-
-Tom Christiansen wrote the original version of this document.
-brian d foy C<< <bdfoy@cpan.org> >> wrote this version. See the
-individual perlfaq documents for additional copyright information.
-
-This document is available under the same terms as Perl itself. Code
-examples in all the perlfaq documents are in the public domain. Use
-them as you see fit (and at your own risk with no warranty from anyone).
+Try the resources in L<perlfaq2>.
 
-=head1 Table of Contents
+=head1 TABLE OF CONTENTS
 
 =over 4
 
-=item perlfaq  - this document
-
 =item perlfaq1 - General Questions About Perl
 
 =item perlfaq2 - Obtaining and Learning about Perl
@@ -87,7 +63,7 @@ them as you see fit (and at your own risk with no warranty from anyone).
 
 =back
 
-=head1 The Questions
+=head1 THE QUESTIONS
 
 =head2 L<perlfaq1>: General Questions About Perl
 
@@ -1377,7 +1353,7 @@ How do I return the user's mail address?
 
 =item *
 
-How do I send mail?
+How do I send email?
 
 =item *
 
@@ -1385,7 +1361,7 @@ How do I use MIME to make an attachment to a mail message?
 
 =item *
 
-How do I read mail?
+How do I read email?
 
 =item *
 
@@ -1404,3 +1380,22 @@ How do I fetch/put an FTP file?
 How can I do RPC in Perl?
 
 =back
+
+
+=head1 CREDITS
+
+Tom Christiansen wrote the original perlfaq then expanded it with the
+help of Nat Torkington. brian d foy substantialy edited and expanded
+the perlfaq. perlfaq-workers and others have also supplied feedback, 
+patches and corrections over the years.
+
+=head1 AUTHOR AND COPYRIGHT
+
+Tom Christiansen wrote the original version of this document.
+brian d foy C<< <bdfoy@cpan.org> >> wrote this version. See the
+individual perlfaq documents for additional copyright information.
+
+This document is available under the same terms as Perl itself. Code
+examples in all the perlfaq documents are in the public domain. Use
+them as you see fit (and at your own risk with no warranty from anyone).
+
diff --git a/cpan/perlfaq/lib/perlfaq2.pod b/cpan/perlfaq/lib/perlfaq2.pod
index 88fb1eacec..c5186ea552 100644
--- a/cpan/perlfaq/lib/perlfaq2.pod
+++ b/cpan/perlfaq/lib/perlfaq2.pod
@@ -8,9 +8,9 @@ This section of the FAQ answers questions about where to find
 source and documentation for Perl, support, and
 related matters.
 
-=head2 What machines support perl? Where do I get it?
+=head2 What machines support Perl? Where do I get it?
 
-The standard release of perl (the one maintained by the perl
+The standard release of Perl (the one maintained by the Perl
 development team) is distributed only in source code form. You
 can find the latest releases at L<http://www.cpan.org/src/>.
 
@@ -29,7 +29,7 @@ of the particular platform that are not supported in the source
 release of perl) or negative (e.g. might be based upon a less current
 source release of perl).
 
-=head2 How can I get a binary version of perl?
+=head2 How can I get a binary version of Perl?
 
 See L<CPAN Ports|http://www.cpan.org/ports/>
 
@@ -44,7 +44,7 @@ Otherwise if you really do want to build Perl, you need to get a
 binary version of C<gcc> for your system first. Use a search 
 engine to find out how to do this for your operating system.
 
-=head2 I copied the perl binary from one machine to another, but scripts don't work.
+=head2 I copied the Perl binary from one machine to another, but scripts don't work.
 
 That's probably because you forgot libraries, or library paths differ.
 You really should build the whole distribution on the machine it will
@@ -103,8 +103,6 @@ you should review as a good starting point.
 
 =item * L<http://learn.perl.org/>
 
-=item * L<http://faq.perl.org/>
-
 =back
 
 The complete Perl documentation is available with the Perl distribution.
diff --git a/cpan/perlfaq/lib/perlfaq3.pod b/cpan/perlfaq/lib/perlfaq3.pod
index a265acfc15..01502c8385 100644
--- a/cpan/perlfaq/lib/perlfaq3.pod
+++ b/cpan/perlfaq/lib/perlfaq3.pod
@@ -157,26 +157,6 @@ You can also use L<Devel::REPL> which is an interactive shell for Perl,
 commonly known as a REPL - Read, Evaluate, Print, Loop. It provides
 various handy features.
 
-
-=head2 Is there a Perl shell?
-
-The L<psh> (Perl sh) is currently at version 1.8. The Perl Shell is a shell
-that combines the interactive nature of a Unix shell with the power of
-Perl. The goal is a full-featured shell that behaves as expected for
-normal shell activity and uses Perl syntax and functionality for
-control-flow statements and other things. You can get L<psh> at
-L<https://metacpan.org/release/psh> .
-
-L<Zoidberg> is a similar project and provides a shell written in perl,
-configured in perl and operated in perl. It is intended as a login shell
-and development environment. It can be found at
-L<https://metacpan.org/release/Zoidberg>.
-
-The C<Shell.pm> module (distributed with Perl) makes Perl try commands
-which aren't part of the Perl language as shell commands. C<perlsh> from
-the source distribution is simplistic and uninteresting, but may still
-be what you want.
-
 =head2 How do I find which modules are installed on my system?
 
 From the command line, you can use the C<cpan> command's C<-l> switch:
@@ -303,8 +283,7 @@ similar to the L<Devel::Cover> report:
 
     nytprofhtml
 
-CPAN has several other profilers that you can invoke in the same
-fashion. You might also be interested in using the L<Benchmark> to
+You might also be interested in using the L<Benchmark> to
 measure and compare code snippets.
 
 You can read more about profiling in I<Programming Perl>, chapter 20,
@@ -456,7 +435,7 @@ Visual Perl is a Visual Studio.NET plug-in from ActiveState.
 
 L<http://www.zeusedit.com/lookmain.html>
 
-Zeus for Windows is another Win32 multi-language editor/IDE
+Zeus for Window is another Win32 multi-language editor/IDE
 that comes with support for Perl.
 
 =back
diff --git a/cpan/perlfaq/lib/perlfaq5.pod b/cpan/perlfaq/lib/perlfaq5.pod
index 325b2cc060..751ee46aed 100644
--- a/cpan/perlfaq/lib/perlfaq5.pod
+++ b/cpan/perlfaq/lib/perlfaq5.pod
@@ -845,7 +845,7 @@ C<Argument list too long>. People who installed tcsh as csh won't
 have this problem, but their users may be surprised by it.
 
 To get around this, either upgrade to Perl v5.6.0 or later, do the glob
-yourself with readdir() and patterns, or use a module like File::KGlob,
+yourself with readdir() and patterns, or use a module like L<File::Glob>,
 one that doesn't use the shell to do globbing.
 
 =head2 Is there a leak/bug in glob()?
@@ -1023,8 +1023,8 @@ simple as this works:
 However, if you have fixed sized records, then you might do something more
 like this:
 
-    $RECSIZE = 220; # size of record, in bytes
-    $recno   = 37;  # which record to update
+    my $RECSIZE = 220; # size of record, in bytes
+    my $recno   = 37;  # which record to update
     open my $fh, '+<', 'somewhere' or die "can't update somewhere: $!";
     seek $fh, $recno * $RECSIZE, 0;
     read $fh, $record, $RECSIZE == $RECSIZE or die "can't read record $recno: $!";
@@ -1053,7 +1053,7 @@ Here's an example:
 
     my $write_secs = (stat($file))[9];
     printf "file %s updated at %s\n", $file,
-    scalar localtime($write_secs);
+        scalar localtime($write_secs);
 
 If you prefer something more legible, use the File::stat module
 (part of the standard distribution in version 5.004 and later):
@@ -1098,12 +1098,12 @@ the filesystems, not of utime().
 X<print, to multiple files>
 
 To connect one filehandle to several output filehandles,
-you can use the IO::Tee or Tie::FileHandle::Multiplex modules.
+you can use the L<IO::Tee> or L<Tie::FileHandle::Multiplex> modules.
 
 If you only have to do this once, you can print individually
 to each filehandle.
 
-    for my $fh (FH1, FH2, FH3) { print $fh "whatever\n" }
+    for my $fh ($fh1, $fh2, $fh3) { print $fh "whatever\n" }
 
 =head2 How can I read in an entire file all at once?
 X<slurp> X<file, slurping>
@@ -1325,21 +1325,21 @@ X<tail> X<IO::Handle> X<File::Tail> X<clearerr>
 
 First try
 
-    seek(GWFILE, 0, 1);
+    seek($gw_fh, 0, 1);
 
-The statement C<seek(GWFILE, 0, 1)> doesn't change the current position,
+The statement C<seek($gw_fh, 0, 1)> doesn't change the current position,
 but it does clear the end-of-file condition on the handle, so that the
-next C<< <GWFILE> >> makes Perl try again to read something.
+next C<< <$gw_fh> >> makes Perl try again to read something.
 
 If that doesn't work (it relies on features of your stdio implementation),
 then you need something more like this:
 
     for (;;) {
-      for ($curpos = tell(GWFILE); <GWFILE>; $curpos = tell(GWFILE)) {
+      for ($curpos = tell($gw_fh); <$gw_fh>; $curpos =tell($gw_fh)) {
         # search for some stuff and put it into files
       }
       # sleep for a while
-      seek(GWFILE, $curpos, 0);  # seek to where we had been
+      seek($gw_fh, $curpos, 0);  # seek to where we had been
     }
 
 If this still doesn't work, look into the C<clearerr> method
@@ -1355,7 +1355,7 @@ If you check L<perlfunc/open>, you'll see that several of the ways
 to call open() should do the trick. For example:
 
     open my $log, '>>', '/foo/logfile';
-    open STDERR, '>&LOG';
+    open STDERR, '>&', $log;
 
 Or even with a literal numeric descriptor:
 
@@ -1392,7 +1392,7 @@ to, you may be able to do this:
 Or, just use the fdopen(3S) feature of C<open()>:
 
     {
-        open my( $fh ), "<&=$fd" or die "Cannot reopen fd=$fd: $!";
+        open my $fh, "<&=$fd" or die "Cannot reopen fd=$fd: $!";
         close $fh;
     }
 
diff --git a/cpan/perlfaq/lib/perlfaq6.pod b/cpan/perlfaq/lib/perlfaq6.pod
index e60d1dfd71..4f6c562462 100644
--- a/cpan/perlfaq/lib/perlfaq6.pod
+++ b/cpan/perlfaq/lib/perlfaq6.pod
@@ -95,8 +95,8 @@ got a multiline string in there.
 For example, this program detects duplicate words, even when they span
 line breaks (but not paragraph ones). For this example, we don't need
 C</s> because we aren't using dot in a regular expression that we want
-to cross line boundaries. Neither do we need C</m> because we aren't
-wanting caret or dollar to match at any point inside the record next
+to cross line boundaries. Neither do we need C</m> because we don't
+want caret or dollar to match at any point inside the record next
 to newlines. But it's imperative that $/ be set to something other
 than the default, or else we won't actually ever have a multiline
 record read in.
@@ -108,7 +108,7 @@ record read in.
         }
     }
 
-Here's code that finds sentences that begin with "From " (which would
+Here's some code that finds sentences that begin with "From " (which would
 be mangled by many mailers):
 
     $/ = '';          # read in whole paragraph, not just one line
@@ -146,8 +146,8 @@ on matching balanced text.
 Here's another example of using C<..>:
 
     while (<>) {
-        $in_header =   1  .. /^$/;
-        $in_body   = /^$/ .. eof;
+        my $in_header =   1  .. /^$/;
+        my $in_body   = /^$/ .. eof;
     # now choose between them
     } continue {
         $. = 0 if eof;    # fix $.
@@ -163,7 +163,7 @@ If you just want to get work done, use a module and forget about the
 regular expressions. The L<XML::Parser> and L<HTML::Parser> modules
 are good starts, although each namespace has other parsing modules
 specialized for certain tasks and different ways of doing it. Start at
-CPAN Search ( L<http://search.cpan.org> ) and wonder at all the work people
+CPAN Search ( L<http://search.cpan.org/> ) and wonder at all the work people
 have done for you already! :)
 
 The problem with things such as XML is that they have balanced text
@@ -201,7 +201,7 @@ X<$RS, regexes in>
 $/ has to be a string. You can use these examples if you really need to
 do this.
 
-If you have File::Stream, this is easy.
+If you have L<File::Stream>, this is easy.
 
     use File::Stream;
 
@@ -304,9 +304,9 @@ the case of the last character is used for the rest of the substitution.
     sub preserve_case($$)
     {
         my ($old, $new) = @_;
-        my ($state) = 0; # 0 = no change; 1 = lc; 2 = uc
+        my $state = 0; # 0 = no change; 1 = lc; 2 = uc
         my ($i, $oldlen, $newlen, $c) = (0, length($old), length($new));
-        my ($len) = $oldlen < $newlen ? $oldlen : $newlen;
+        my $len = $oldlen < $newlen ? $oldlen : $newlen;
 
         for ($i = 0; $i < $len; $i++) {
             if ($c = substr($old, $i, 1), $c =~ /[\W\d_]/) {
@@ -433,7 +433,7 @@ later, you should only see C<re> report that for the first iteration.
 
     use re 'debug';
 
-    $regex = 'Perl';
+    my $regex = 'Perl';
     foreach ( qw(Perl Java Ruby Python) ) {
         print STDERR "-" x 73, "\n";
         print STDERR "Trying $_...\n";
@@ -640,7 +640,7 @@ versions of the same quantifiers, use (C<??>, C<*?>, C<+?>, C<{}?>).
 
 An example:
 
-    $s1 = $s2 = "I am very very cold";
+    my $s1 = my $s2 = "I am very very cold";
     $s1 =~ s/ve.*y //;      # I am cold
     $s2 =~ s/ve.*?y //;     # I am very cold
 
@@ -656,7 +656,7 @@ X<word>
 Use the split function:
 
     while (<>) {
-        foreach $word ( split ) {
+        foreach my $word ( split ) {
             # do something with $word here
         }
     }
@@ -680,24 +680,27 @@ pretend that by word you mean chunk of alphabetics, hyphens, or
 apostrophes, rather than the non-whitespace chunk idea of a word given
 in the previous question:
 
+    my (%seen);
     while (<>) {
         while ( /(\b[^\W_\d][\w'-]+\b)/g ) {   # misses "`sheep'"
             $seen{$1}++;
         }
     }
 
-    while ( ($word, $count) = each %seen ) {
+    while ( my ($word, $count) = each %seen ) {
         print "$count $word\n";
     }
 
 If you wanted to do the same thing for lines, you wouldn't need a
 regular expression:
 
+    my (%seen);
+
     while (<>) {
         $seen{$_}++;
     }
 
-    while ( ($line, $count) = each %seen ) {
+    while ( my ($line, $count) = each %seen ) {
         print "$count $line";
     }
 
@@ -707,7 +710,7 @@ sort a hash (optionally by value instead of key)?".
 =head2 How can I do approximate matching?
 X<match, approximate> X<matching, approximate>
 
-See the module String::Approx available from CPAN.
+See the module L<String::Approx> available from CPAN.
 
 =head2 How do I efficiently match many regular expressions at once?
 X<regex, efficiency> X<regexp, efficiency>
@@ -772,8 +775,8 @@ though.
     }
 
 For more details on regular expression efficiency, see I<Mastering
-Regular Expressions> by Jeffrey Friedl. He explains how regular
-expressions engine work and why some patterns are surprisingly
+Regular Expressions> by Jeffrey Friedl. He explains how the regular
+expressions engine works and why some patterns are surprisingly
 inefficient. Once you understand how perl applies regular expressions,
 you can tune them for individual situations.
 
@@ -1022,17 +1025,20 @@ Here are a few ways, all painful, to deal with it:
 
 Or like this:
 
-    @chars = $martian =~ m/([A-Z][A-Z]|[^A-Z])/g;
-    # above is conceptually similar to:     @chars = $text =~ m/(.)/g;
+    my @chars = $martian =~ m/([A-Z][A-Z]|[^A-Z])/g;
+    # above is conceptually similar to:     my @chars = $text =~ m/(.)/g;
     #
-    foreach $char (@chars) {
+    foreach my $char (@chars) {
         print "found GX!\n", last if $char eq 'GX';
     }
 
 Or like this:
 
     while ($martian =~ m/\G([A-Z][A-Z]|.)/gs) {  # \G probably unneeded
-        print "found GX!\n", last if $1 eq 'GX';
+        if ($1 eq 'GX') {
+            print "found GX!\n";
+            last;
+        }
     }
 
 Here's another, slightly less painful, way to do it from Benjamin
diff --git a/cpan/perlfaq/lib/perlfaq7.pod b/cpan/perlfaq/lib/perlfaq7.pod
index 96c621a31d..293834c76d 100644
--- a/cpan/perlfaq/lib/perlfaq7.pod
+++ b/cpan/perlfaq/lib/perlfaq7.pod
@@ -63,13 +63,13 @@ list. Good style (see L<perlstyle>) says to put them in except for
 one-liners:
 
     if ($whoops) { exit 1 }
-    @nums = (1, 2, 3);
+    my @nums = (1, 2, 3);
 
     if ($whoops) {
         exit 1;
     }
 
-    @lines = (
+    my @lines = (
         "There Beren came from mountains cold",
         "And lost he wandered under leaves",
     );
@@ -92,12 +92,12 @@ you need:
 =head2 How do I temporarily block warnings?
 
 If you are running Perl 5.6.0 or better, the C<use warnings> pragma
-allows fine control of what warning are produced.
+allows fine control of what warnings are produced.
 See L<perllexwarn> for more details.
 
     {
         no warnings;          # temporarily turn off warnings
-        $a = $b + $c;         # I know these might be undef
+        $x = $y + $z;         # I know these might be undef
     }
 
 Additionally, you can enable and disable categories of warnings.
@@ -107,7 +107,7 @@ complete details, including the category names and hierarchy.
 
     {
         no warnings 'uninitialized';
-        $a = $b + $c;
+        $x = $y + $z;
     }
 
 If you have an older version of Perl, the C<$^W> variable (documented
@@ -115,7 +115,7 @@ in L<perlvar>) controls runtime warnings for a block:
 
     {
         local $^W = 0;        # temporarily turn off warnings
-        $a = $b + $c;         # I know these might be undef
+        $x = $y + $z;         # I know these might be undef
     }
 
 Note that like all the punctuation variables, you cannot currently
@@ -155,14 +155,14 @@ just such situations as the one above.
 
 Another operator with surprising precedence is exponentiation. It
 binds more tightly even than unary minus, making C<-2**2> produce a
-negative not a positive four. It is also right-associating, meaning
+negative four and not a positive one. It is also right-associating, meaning
 that C<2**3**2> is two raised to the ninth power, not eight squared.
 
 Although it has the same precedence as in C, Perl's C<?:> operator
-produces an lvalue. This assigns $x to either $a or $b, depending
+produces an lvalue. This assigns $x to either $if_true or $if_false, depending
 on the trueness of $maybe:
 
-    ($maybe ? $a : $b) = $x;
+    ($maybe ? $if_true : $if_false) = $x;
 
 =head2 How do I declare/create a structure?
 
@@ -284,8 +284,8 @@ Here's a classic non-closure function-generating function:
         return sub { shift() + shift() };
     }
 
-    $add_sub = add_function_generator();
-    $sum = $add_sub->(4,5);                # $sum is 9 now.
+    my $add_sub = add_function_generator();
+    my $sum = $add_sub->(4,5);                # $sum is 9 now.
 
 The anonymous subroutine returned by add_function_generator() isn't
 technically a closure because it refers to no lexicals outside its own
@@ -303,11 +303,11 @@ value that the lexical had when the function was created.
         return sub { shift() + $addpiece };
     }
 
-    $f1 = make_adder(20);
-    $f2 = make_adder(555);
+    my $f1 = make_adder(20);
+    my $f2 = make_adder(555);
 
-Now C<&$f1($n)> is always 20 plus whatever $n you pass in, whereas
-C<&$f2($n)> is always 555 plus whatever $n you pass in. The $addpiece
+Now C<< $f1->($n) >> is always 20 plus whatever $n you pass in, whereas
+C<< $f2->($n) >> is always 555 plus whatever $n you pass in. The $addpiece
 in the closure sticks around.
 
 Closures are often used for less esoteric purposes. For example, when
@@ -356,9 +356,9 @@ variable's value this way, but now it's much harder. Take this code:
     print "Finally $f\n";
 
 If you are experiencing variable suicide, that C<my $f> in the subroutine
-doesn't pick up a fresh copy of the C<$f> whose value is <foo>. The output
-shows that inside the subroutine the value of C<$f> leaks through when it
-shouldn't, as in this output:
+doesn't pick up a fresh copy of the C<$f> whose value is C<'foo'>. The
+output shows that inside the subroutine the value of C<$f> leaks through
+when it shouldn't, as in this output:
 
     foobar
     foobarbar
@@ -425,7 +425,7 @@ operator:
     sub compare($$) {
         my ($val1, $regex) = @_;
         my $retval = $val1 =~ /$regex/;
-    return $retval;
+        return $retval;
     }
     $match = compare("old McDonald", qr/d.*D/i);
 
@@ -444,7 +444,7 @@ To pass an object method into a subroutine, you can do this:
 Or, you can use a closure to bundle up the object, its
 method call, and arguments:
 
-    my $whatnot =  sub { $some_obj->obfuscate(@args) };
+    my $whatnot = sub { $some_obj->obfuscate(@args) };
     func($whatnot);
     sub func {
         my $code = shift;
@@ -604,10 +604,10 @@ However, dynamic variables (aka global, local, or package variables)
 are effectively shallowly bound. Consider this just one more reason
 not to use them. See the answer to L<"What's a closure?">.
 
-=head2 Why doesn't "my($foo) = E<lt>FILEE<gt>;" work right?
+=head2 Why doesn't "my($foo) = E<lt>$fh<gt>;" work right?
 
 C<my()> and C<local()> give list context to the right hand side
-of C<=>. The <FH> read operation, like so many of Perl's
+of C<=>. The <$fh> read operation, like so many of Perl's
 functions and operators, can tell which context it was called in and
 behaves appropriately. In general, the scalar() function can help.
 This function does nothing to the data itself (contrary to popular myth)
@@ -618,15 +618,15 @@ doesn't help you (such as with sort()).
 To enforce scalar context in this particular case, however, you need
 merely omit the parentheses:
 
-    local($foo) = <FILE>;        # WRONG
-    local($foo) = scalar(<FILE>);   # ok
-    local $foo  = <FILE>;        # right
+    local($foo) = <$fh>;        # WRONG
+    local($foo) = scalar(<$fh>);   # ok
+    local $foo  = <$fh>;        # right
 
 You should probably be using lexical variables anyway, although the
 issue is the same here:
 
-    my($foo) = <FILE>;    # WRONG
-    my $foo  = <FILE>;    # right
+    my($foo) = <$fh>;    # WRONG
+    my $foo  = <$fh>;    # right
 
 =head2 How do I redefine a builtin function, operator, or method?
 
@@ -861,7 +861,7 @@ You can safely replace C<isa> with C<DOES> (although the converse is not true).
 The quick-and-dirty way to comment out more than one line of Perl is
 to surround those lines with Pod directives. You have to put these
 directives at the beginning of the line and somewhere where Perl
-expects a new statement (so not in the middle of statements like the #
+expects a new statement (so not in the middle of statements like the C<#>
 comments). You end the comment with C<=cut>, ending the Pod section:
 
     =pod
@@ -954,7 +954,7 @@ symbolic references, you are just using the package's symbol-table hash
 use your own hash or a real reference instead.
 
     $USER_VARS{"fred"} = 23;
-    $varname = "fred";
+    my $varname = "fred";
     $USER_VARS{$varname}++;  # not $$varname++
 
 There we're using the %USER_VARS hash instead of symbolic references.
diff --git a/cpan/perlfaq/lib/perlfaq8.pod b/cpan/perlfaq/lib/perlfaq8.pod
index 72447256d7..552e00b69c 100644
--- a/cpan/perlfaq/lib/perlfaq8.pod
+++ b/cpan/perlfaq/lib/perlfaq8.pod
@@ -55,6 +55,9 @@ How you access/control keyboards, screens, and pointing devices
 =item Mouse
 
     Tk                      CPAN
+    Wx                      CPAN
+    Gtk2                    CPAN
+    Qt4                     kdebindings4 package
 
 =back
 
@@ -115,10 +118,12 @@ to manipulate the POSIX termios structures.
     # HotKey.pm
     package HotKey;
 
-    @ISA = qw(Exporter);
-    @EXPORT = qw(cbreak cooked readkey);
-
     use strict;
+    use warnings;
+
+    use parent 'Exporter';
+    our @EXPORT = qw(cbreak cooked readkey);
+
     use POSIX qw(:termios_h);
     my ($term, $oterm, $echo, $noecho, $fd_stdin);
 
@@ -164,7 +169,7 @@ not to block:
 
     ReadMode('cbreak');
 
-    if (defined ($char = ReadKey(-1)) ) {
+    if (defined (my $char = ReadKey(-1)) ) {
         # input was waiting and it was $char
     } else {
         # no input was waiting
@@ -194,8 +199,8 @@ method returns the string for the given capability:
 
     use Term::Cap;
 
-    $terminal = Term::Cap->Tgetent( { OSPEED => 9600 } );
-    $clear_string = $terminal->Tputs('cl');
+    my $terminal = Term::Cap->Tgetent( { OSPEED => 9600 } );
+    my $clear_string = $terminal->Tputs('cl');
 
     print $clear_screen;
 
@@ -205,7 +210,7 @@ C<Cls> method:
 
     Win32::Console;
 
-    $OUT = Win32::Console->new(STD_OUTPUT_HANDLE);
+    my $OUT = Win32::Console->new(STD_OUTPUT_HANDLE);
     my $clear_string = $OUT->Cls;
 
     print $clear_screen;
@@ -214,7 +219,7 @@ If you have a command-line program that does the job, you can call
 it in backticks to capture whatever it outputs so you can use it
 later:
 
-    $clear_string = `clear`;
+    my $clear_string = `clear`;
 
     print $clear_string;
 
@@ -225,18 +230,18 @@ you can use it to fetch the width and height in characters
 and in pixels:
 
     use Term::ReadKey;
-    ($wchar, $hchar, $wpixels, $hpixels) = GetTerminalSize();
+    my ($wchar, $hchar, $wpixels, $hpixels) = GetTerminalSize();
 
 This is more portable than the raw C<ioctl>, but not as
 illustrative:
 
     require 'sys/ioctl.ph';
     die "no TIOCGWINSZ " unless defined &TIOCGWINSZ;
-    open(TTY, "+</dev/tty")                     or die "No tty: $!";
-    unless (ioctl(TTY, &TIOCGWINSZ, $winsize='')) {
+    open(my $tty_fh, "+</dev/tty")                     or die "No tty: $!";
+    unless (ioctl($tty_fh, &TIOCGWINSZ, $winsize='')) {
         die sprintf "$0: ioctl TIOCGWINSZ (%08x: $!)\n", &TIOCGWINSZ;
     }
-    ($row, $col, $xpixel, $ypixel) = unpack('S4', $winsize);
+    my ($row, $col, $xpixel, $ypixel) = unpack('S4', $winsize);
     print "(row,col) = ($row,$col)";
     print "  (xpixel,ypixel) = ($xpixel,$ypixel)" if $xpixel || $ypixel;
     print "\n";
@@ -258,13 +263,13 @@ from CPAN, which is easier to use and in theory more portable.
     use Term::ReadKey;
 
     ReadMode('noecho');
-    $password = ReadLine(0);
+    my $password = ReadLine(0);
 
 =head2 How do I read and write the serial port?
 
 This depends on which operating system your program is running on. In
 the case of Unix, the serial ports will be accessible through files in
-/dev; on other systems, device names will doubtless differ.
+C</dev>; on other systems, device names will doubtless differ.
 Several problem areas common to all device interaction are the
 following:
 
@@ -311,19 +316,19 @@ and the C<$|> variable to control autoflushing (see L<perlvar/$E<verbar>>
 and L<perlfunc/select>, or L<perlfaq5>, "How do I flush/unbuffer an
 output filehandle? Why must I do this?"):
 
-    $oldh = select(DEV);
+    my $old_handle = select($dev_fh);
     $| = 1;
-    select($oldh);
+    select($old_handle);
 
 You'll also see code that does this without a temporary variable, as in
 
-    select((select(DEV), $| = 1)[0]);
+    select((select($deb_handle), $| = 1)[0]);
 
 Or if you don't mind pulling in a few thousand lines
 of code just because you're afraid of a little C<$|> variable:
 
     use IO::Handle;
-    DEV->autoflush(1);
+    $dev_fh->autoflush(1);
 
 As mentioned in the previous item, this still doesn't work when using
 socket I/O between Unix and Macintosh. You'll need to hard code your
@@ -383,7 +388,7 @@ L<passwd(1)>, for example).
 There's not a single way to run code in the background so you don't
 have to wait for it to finish before your program moves on to other
 tasks. Process management depends on your particular operating system,
-and many of the techniques are in L<perlipc>.
+and many of the techniques are covered in L<perlipc>.
 
 Several CPAN modules may be able to help, including L<IPC::Open2> or
 L<IPC::Open3>, L<IPC::Run>, L<Parallel::Jobs>,
@@ -498,7 +503,7 @@ probably get away with setting an environment variable:
 
     $ENV{TZ} = "MST7MDT";           # Unixish
     $ENV{'SYS$TIMEZONE_DIFFERENTIAL'}="-5" # vms
-    system "trn comp.lang.perl.misc";
+    system('trn', 'comp.lang.perl.misc');
 
 =head2 How can I sleep() or alarm() for under a second?
 X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select>
@@ -586,7 +591,7 @@ Simple files like F<errno.h>, F<syscall.h>, and F<socket.h> were fine,
 but the hard ones like F<ioctl.h> nearly always need to be hand-edited.
 Here's how to install the *.ph files:
 
-    1. become super-user
+    1. Become the super-user
     2. cd /usr/include
     3. h2ph *.h */*.h
 
@@ -627,16 +632,16 @@ the low 7 bits are the signal the process died from, if any, and
 the high 8 bits are the actual exit value). Backticks (``) run a
 command and return what it sent to STDOUT.
 
-    $exit_status   = system("mail-users");
-    $output_string = `ls`;
+    my $exit_status   = system("mail-users");
+    my $output_string = `ls`;
 
 =head2 How can I capture STDERR from an external command?
 
 There are three basic ways of running external commands:
 
     system $cmd;        # using system()
-    $output = `$cmd`;        # using backticks (``)
-    open (PIPE, "cmd |");    # using open()
+    my $output = `$cmd`;        # using backticks (``)
+    open (my $pipe_fh, "$cmd |");    # using open()
 
 With C<system()>, both STDOUT and STDERR will go the same place as the
 script's STDOUT and STDERR, unless the C<system()> command redirects them.
@@ -877,8 +882,8 @@ do it. Here are some less reliable workarounds:
 
 Try keeping around the seekpointer and go there, like this:
 
-    $where = tell(LOG);
-    seek(LOG, $where, 0);
+    my $where = tell($log_fh);
+    seek($log_fh, $where, 0);
 
 =item 2
 
@@ -919,7 +924,7 @@ the initial telnet handshaking, then the standard dual-process
 approach will suffice:
 
     use IO::Socket;             # new in 5.004
-    $handle = IO::Socket::INET->new('L<www.perl.com:80')>
+    my $handle = IO::Socket::INET->new('L<www.perl.com:80')>
         or die "can't connect to port 80 on L<www.perl.com:> $!";
     $handle->autoflush(1);
     if (fork()) {               # XXX: undef means failure
@@ -936,7 +941,7 @@ approach will suffice:
 Once upon a time, there was a library called F<chat2.pl> (part of the
 standard perl distribution), which never really got finished. If you
 find it somewhere, I<don't use it>. These days, your best bet is to
-look at the Expect module available from CPAN, which also requires two
+look at the L<Expect> module available from CPAN, which also requires two
 other modules from CPAN, L<IO::Pty> and L<IO::Stty>.
 
 =head2 Is there a way to hide perl's command line from programs such as "ps"?
@@ -1094,10 +1099,10 @@ servers and types, including Oracle, DB2, Sybase, mysql, Postgresql,
 ODBC, and flat files. The DBI module accesses each database type
 through a database driver, or DBD. You can see a complete list of
 available drivers on CPAN: L<http://www.cpan.org/modules/by-module/DBD/> .
-You can read more about DBI on L<http://dbi.perl.org> .
+You can read more about DBI on L<http://dbi.perl.org/> .
 
 Other modules provide more specific access: L<Win32::ODBC>, L<Alzabo>,
-C<iodbc>, and others found on CPAN Search: L<http://search.cpan.org> .
+C<iodbc>, and others found on CPAN Search: L<http://search.cpan.org/> .
 
 =head2 How do I make a system() exit on control-C?
 
@@ -1116,7 +1121,7 @@ C<O_NDELAY> or C<O_NONBLOCK> flag from the C<Fcntl> module in conjunction with
 C<sysopen()>:
 
     use Fcntl;
-    sysopen(FH, "/foo/somefile", O_WRONLY|O_NDELAY|O_CREAT, 0644)
+    sysopen(my $fh, "/foo/somefile", O_WRONLY|O_NDELAY|O_CREAT, 0644)
         or die "can't open /foo/somefile: $!":
 
 =head2 How do I tell the difference between errors from the shell and perl?
@@ -1399,7 +1404,8 @@ included with the 5.002 release of Perl.
 
 It's a Perl 4 style file defining values for system networking
 constants. Sometimes it is built using L<h2ph> when Perl is installed,
-but other times it is not. Modern programs C<use Socket;> instead.
+but other times it is not. Modern programs should use C<use Socket;>
+instead.
 
 =head1 AUTHOR AND COPYRIGHT
 
diff --git a/cpan/perlfaq/lib/perlfaq9.pod b/cpan/perlfaq/lib/perlfaq9.pod
index 63bb80e67d..dc71115f1a 100644
--- a/cpan/perlfaq/lib/perlfaq9.pod
+++ b/cpan/perlfaq/lib/perlfaq9.pod
@@ -4,8 +4,8 @@ perlfaq9 - Networking
 
 =head1 DESCRIPTION
 
-This section deals with questions related to networking, the internet,
-and a few on the web.
+This section deals with questions related to networking, the Internet,
+and a few about the Web.
 
 =head2 What is the correct form of response from a CGI script?
 
@@ -13,8 +13,8 @@ and a few on the web.
 
 The Common Gateway Interface (CGI) specifies a software interface between
 a program ("CGI script") and a web server (HTTPD). It is not specific
-to Perl, and has its own FAQs and tutorials, and usenet group,
-comp.infosystems.L<www.authoring.cgi>
+to Perl, and has its own FAQs and tutorials, and a Usenet group,
+comp.infosystems.www.authoring.cgi.
 
 The CGI specification is outlined in an informational RFC:
 L<http://www.ietf.org/rfc/rfc3875>
@@ -50,7 +50,7 @@ systems. C<CGI.pm> selects an appropriate newline representation
 There are many things that might be wrong with your CGI program, and only
 some of them might be related to Perl. Try going through the L<troubleshooting
 guide|L<http://www.perlmonks.org/?node_id=380424>> on 
-L<Perlmonks|L<http://www.perlmonks.org>>
+L<Perlmonks|L<http://www.perlmonks.org/>> .
 
 =head2 How can I get better error messages from a CGI program?
 
@@ -66,9 +66,10 @@ server error log.
 The following use of L<CGI::Carp> also redirects errors to a file of your choice,
 placed in a C<BEGIN> block to catch compile-time warnings as well:
 
+    use vars qw($log_fh);
     BEGIN {
         use CGI::Carp qw(carpout);
-        open(LOG, ">>/var/local/cgi-logs/mycgi-log")
+        open($log_fh, ">>/var/local/cgi-logs/mycgi-log")
             or die "Unable to append to mycgi-log: $!\n";
         carpout(*LOG);
     }
@@ -203,13 +204,13 @@ resources and give their content back to you as a string:
 
     use LWP::Simple qw(get);
 
-    my $html = get( "L<http://www.example.com/index.html"> );
+    my $html = get( "http://www.example.com/index.html" );
 
 It can also store the resource directly in a file:
 
     use LWP::Simple qw(getstore);
 
-    getstore( "L<http://www.example.com/index.html">, "foo.html" );
+    getstore( "http://www.example.com/index.html", "foo.html" );
 
 If you need to do something more complicated, you can use
 L<LWP::UserAgent> module to create your own user-agent (e.g. browser)
@@ -238,10 +239,10 @@ the content appropriately.
     use HTTP::Request::Common qw(POST);
     use LWP::UserAgent;
 
-    $ua = LWP::UserAgent->new();
+    my $ua = LWP::UserAgent->new();
     my $req = POST 'L<http://www.perl.com/cgi-bin/cpan_mod'>,
                    [ module => 'DB_File', readme => 1 ];
-    $content = $ua->request($req)->as_string;
+    my $content = $ua->request($req)->as_string;
 
 =head2 How do I decode or create those %-encodings on the web?
 X<URI> X<CGI.pm> X<CGI> X<URI::Escape> X<RFC 2396>
@@ -336,7 +337,7 @@ a DBI compatible driver. L<HTTPD::UserAdmin> supports files used by the
       ->new(DB => "/foo/.htpasswd")
       ->add($username => $password);
 
-=head2 How do I make sure users can't enter values into a form that cause my CGI script to do bad things?
+=head2 How do I make sure users can't enter values into a form that causes my CGI script to do bad things?
 
 (contributed by brian d foy)
 
@@ -411,7 +412,7 @@ for you, too.
 
 Many people try to write their own decoder (or copy one from
 another program) and then run into one of the many "gotchas"
-of the task. It's much easier and less hassle to use C<CGI.pm>.
+of the task. It's much easier and less of a hassle to use C<CGI.pm>.
 
 =head2 How do I check a valid mail address?
 
@@ -449,7 +450,7 @@ The L<MIME::Base64> package handles this as well as the MIME/QP encoding.
 Decoding base 64 becomes as simple as:
 
     use MIME::Base64;
-    $decoded = decode_base64($encoded);
+    my $decoded = decode_base64($encoded);
 
 The L<Email::MIME> module can decode base 64-encoded email message parts
 transparently so the developer doesn't need to worry about it.
@@ -470,7 +471,7 @@ is correct unless your policy says it is. And then there are things like
 localpart extensions (foo+bar@example.com). You really are best off
 asking the user.
 
-=head2 How do I send mail?
+=head2 How do I send email?
 
 Use the L<Email::MIME> and L<Email::Sender::Simple> modules, like so:
 
@@ -529,7 +530,7 @@ objects themselves are parts and can be attached to other L<Email::MIME>
 objects. Consult the L<Email::MIME> documentation for more information,
 including all of the supported methods and examples of their use.
 
-=head2 How do I read mail?
+=head2 How do I read email?
 
 Use the L<Email::Folder> module, like so:
 
@@ -607,7 +608,7 @@ makes it quite easy to fetch a file:
     my $data = get( 'L<ftp://some.ftp.site/some/file.txt'> );
 
 If you want more direct or low-level control of the FTP process, you can use
-the L<Net::FTP> module (in the Standard Library since Perl 5.8). It's
+the L<Net::FTP> module (in the Standard Library since Perl 5.8). Its
 documentation has examples showing you just how to do that.
 
 =head2 How can I do RPC in Perl?
diff --git a/cpan/perlfaq/lib/perlglossary.pod b/cpan/perlfaq/lib/perlglossary.pod
index 014eb99fd5..94ce6d52df 100644
--- a/cpan/perlfaq/lib/perlglossary.pod
+++ b/cpan/perlfaq/lib/perlglossary.pod
@@ -6,7 +6,7 @@ perlglossary - Perl Glossary
 
 A glossary of terms (technical and otherwise) used in the Perl documentation.
 Other useful sources include the Free On-Line Dictionary of Computing
-L<http://foldoc.doc.ic.ac.uk/foldoc/index.html>, the Jargon File
+L<http://foldoc.org/>, the Jargon File
 L<http://catb.org/~esr/jargon/>, and Wikipedia L<http://www.wikipedia.org/>.
 
 =head2 A
@@ -3385,11 +3385,11 @@ in the three-argument form of L<open|perlfunc/open>.
 
 =item XS
 
-An extraordinarily exported, expeditiously excellent, expressly
-eXternal Subroutine, executed in existing C or C++ or in an exciting
-new extension language called (exasperatingly) XS.  Examine L<perlxs>
-for the exact explanation or L<perlxstut> for an exemplary unexacting
-one.
+A language to extend Perl with L<C> and C++. XS is an interface description 
+file format used to create an extension interface between 
+Perl and C code (or a C library) which one wishes to use with Perl. 
+See L<perlxs> for the exact explanation or read the L<perlxstut>
+tutorial.
 
 =item XSUB