Update perlfaq to CPAN version 5.0150037

  [DELTA]

  5.0150037 Sun  8 Jan 2012 21:24:39 +0100
    * Better XML parsing recommendations (apeiron)
    * Remove various old questions & update a few (ranguard)
    * Change auto generate of questions a bit (ranguard)
    * Autogenerate question index in perlfaq.pod (doherty)
    * Cleanups / typos, updating nested expressions (dami, reviewed by schwern)

10 files changed, 177 insertions, 468 deletions

diff --git a/cpan/perlfaq/lib/perlfaq.pm b/cpan/perlfaq/lib/perlfaq.pm
index 0b97525eb1..b42a6cadcf 100644
--- a/cpan/perlfaq/lib/perlfaq.pm
+++ b/cpan/perlfaq/lib/perlfaq.pm
@@ -1,6 +1,6 @@
 package perlfaq;
 {
-  $perlfaq::VERSION = '5.0150036';
+  $perlfaq::VERSION = '5.0150037';
 }
 
 0; # not is it supposed to be loaded
diff --git a/cpan/perlfaq/lib/perlfaq.pod b/cpan/perlfaq/lib/perlfaq.pod
index ff269a3bb1..4d6053196c 100644
--- a/cpan/perlfaq/lib/perlfaq.pod
+++ b/cpan/perlfaq/lib/perlfaq.pod
@@ -59,7 +59,7 @@ Try the resources in L<perlfaq2>.
 
 =item perlfaq8 - System Interaction
 
-=item perlfaq9 - Networking
+=item perlfaq9 - Web, Email and Networking
 
 =back
 
@@ -134,11 +134,11 @@ This section of the FAQ answers questions about where to find source and documen
 
 =item *
 
-What machines support perl? Where do I get it?
+What machines support Perl? Where do I get it?
 
 =item *
 
-How can I get a binary version of perl?
+How can I get a binary version of Perl?
 
 =item *
 
@@ -146,7 +146,7 @@ I don't have a C compiler. How can I build my own Perl interpreter?
 
 =item *
 
-I copied the perl binary from one machine to another, but scripts don't work.
+I copied the Perl binary from one machine to another, but scripts don't work.
 
 =item *
 
@@ -211,10 +211,6 @@ How can I use Perl interactively?
 
 =item *
 
-Is there a Perl shell?
-
-=item *
-
 How do I find which modules are installed on my system?
 
 =item *
@@ -616,6 +612,10 @@ How can I check if a key exists in a multilevel hash?
 
 =item *
 
+How can I prevent addition of unwanted keys into a hash?
+
+=item *
+
 How do I handle binary data correctly?
 
 =item *
@@ -1015,7 +1015,7 @@ What's the difference between deep and shallow binding?
 
 =item *
 
-Why doesn't "my($foo) = E<lt>FILEE<gt>;" work right?
+Why doesn't "my($foo) = E<lt>$fhE<gt>;" work right?
 
 =item *
 
@@ -1269,23 +1269,23 @@ What is socket.ph and where do I get it?
 =back
 
 
-=head2 L<perlfaq9>: Networking
+=head2 L<perlfaq9>: Web, Email and Networking
 
-This section deals with questions related to networking, the internet, and a few on the web.
+This section deals with questions related to running web sites, sending and receiving email as well as general networking.
 
 =over 4
 
 =item *
 
-What is the correct form of response from a CGI script?
+Should I use a web framework?
 
 =item *
 
-My CGI script runs from the command line but not the browser. (500 Server Error)
+Which web framework should I use?
 
 =item *
 
-How can I get better error messages from a CGI program?
+What is Plack and PSGI?
 
 =item *
 
@@ -1297,14 +1297,6 @@ How do I extract URLs?
 
 =item *
 
-How do I download a file from the user's machine? How do I open a file on another machine?
-
-=item *
-
-How do I make an HTML pop-up menu with Perl?
-
-=item *
-
 How do I fetch an HTML file?
 
 =item *
@@ -1325,11 +1317,7 @@ How do I put a password on my web pages?
 
 =item *
 
-How do I edit my .htpasswd and .htgroup files with Perl?
-
-=item *
-
-How do I make sure users can't enter values into a form that cause my CGI script to do bad things?
+How do I make sure users can't enter values into a form that causes my CGI script to do bad things?
 
 =item *
 
@@ -1337,10 +1325,6 @@ How do I parse a mail header?
 
 =item *
 
-How do I decode a CGI form?
-
-=item *
-
 How do I check a valid mail address?
 
 =item *
@@ -1349,10 +1333,6 @@ How do I decode a MIME/BASE64 string?
 
 =item *
 
-How do I return the user's mail address?
-
-=item *
-
 How do I send email?
 
 =item *
@@ -1369,11 +1349,7 @@ How do I find out my hostname, domainname, or IP address?
 
 =item *
 
-How do I fetch a news article or the active newsgroups?
-
-=item *
-
-How do I fetch/put an FTP file?
+How do I fetch/put an (S)FTP file?
 
 =item *
 
@@ -1382,6 +1358,7 @@ How can I do RPC in Perl?
 =back
 
 
+
 =head1 CREDITS
 
 Tom Christiansen wrote the original perlfaq then expanded it with the
@@ -1398,4 +1375,3 @@ 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/perlfaq1.pod b/cpan/perlfaq/lib/perlfaq1.pod
index 412b6bed00..75560549f0 100644
--- a/cpan/perlfaq/lib/perlfaq1.pod
+++ b/cpan/perlfaq/lib/perlfaq1.pod
@@ -22,8 +22,8 @@ lesser extent from sed, awk, the Unix shell, and many other tools
 and languages.
 
 These strengths make it especially popular with web developers
-and system administrators, but mathematicians, geneticists, journalists,
-and managers also use Perl. Maybe you should, too.
+and system administrators. Mathematicians, geneticists, journalists,
+managers and many other people also use Perl. 
 
 =head2 Who supports Perl? Who develops it? Why is it free?
 
@@ -176,7 +176,7 @@ backward compatibility.
 
 =head2 Is Perl difficult to learn?
 
-No, Perl is easy to start learning--and easy to keep learning. It looks
+No, Perl is easy to start L<learning|http://learn.perl.org/> --and easy to keep learning. It looks
 like most programming languages you're likely to have experience
 with, so if you've ever written a C program, an awk script, a shell
 script, or even a BASIC program, you're already partway there.
@@ -198,17 +198,17 @@ of programming experience, an understanding of regular expressions, and
 the ability to understand other people's code. If there's something you
 need to do, then it's probably already been done, and a working example is
 usually available for free. Don't forget Perl modules, either.
-They're discussed in Part 3 of this FAQ, along with CPAN, which is
+They're discussed in Part 3 of this FAQ, along with L<CPAN|http://www.cpan.org/>, which is
 discussed in Part 2.
 
 =head2 How does Perl compare with other languages like Java, Python, REXX, Scheme, or Tcl?
 
 Perl can be used for almost any coding problem, even ones which require 
-intergrating specialist C code for extra speed. As with any tool it can
+integrating specialist C code for extra speed. As with any tool it can
 be used well or badly. Perl has many strengths, and a few weaknesses,
 precisely which areas are good and bad is often a personal choice. 
 
-When choosing a language you should also be influenced buy the 
+When choosing a language you should also be influenced by the 
 L<resources|http://www.cpan.org/>, L<testing culture|http://www.cpantesters.org/> 
 and L<community|http://www.perl.org/community.html> which surrounds it.
 
@@ -243,9 +243,7 @@ languages that come to mind include prolog and matlab.
 
 =head2 When shouldn't I program in Perl?
 
-When your manager forbids it--but do consider replacing them :-).
-
-Actually, one good reason is when you already have an existing
+One good reason is when you already have an existing
 application written in another language that's all done (and done
 well), or you have an application language specifically designed for a
 certain task (e.g. prolog, make).
@@ -313,9 +311,9 @@ You might find these links useful:
 
 =over 4
 
-=item * L<http://perltraining.com.au/whyperl.html>
+=item * L<http://www.perl.org/about.html>
 
-=item * L<http://www.perl.org/advocacy/whyperl.html>
+=item * L<http://perltraining.com.au/whyperl.html>
 
 =back
 
diff --git a/cpan/perlfaq/lib/perlfaq2.pod b/cpan/perlfaq/lib/perlfaq2.pod
index c5186ea552..7aa63f58ed 100644
--- a/cpan/perlfaq/lib/perlfaq2.pod
+++ b/cpan/perlfaq/lib/perlfaq2.pod
@@ -145,7 +145,7 @@ such as:
 
 L<Perl Mongers|http://www.pm.org/> uses the pm.org domain for services 
 related to local Perl user groups, including the hosting of mailing lists 
-and web sites. See the L<Perl Mongers website|http://www.pm.org/> for more 
+and web sites. See the L<Perl Mongers web site|http://www.pm.org/> for more 
 information about joining, starting, or requesting services for a 
 Perl user group.
 
@@ -178,6 +178,10 @@ Several unix/linux releated magazines frequently includes articles on Perl.
 
 =head2 Which Perl blogs should I read?
 
+L<Perl News|http://perlnews.org/> covers some of the major events in the Perl
+world, L<Perl Weekly|http://perlweekly.com/> is a weekly e-mail 
+(and RSS feed) of hand-picked Perl articles.
+
 L<http://blogs.perl.org/> hosts many Perl blogs, there are also
 several blog aggregators: L<Perlsphere|http://perlsphere.net/> and
 L<IronMan|http://ironman.enlightenedperl.org/> are two of them.
diff --git a/cpan/perlfaq/lib/perlfaq3.pod b/cpan/perlfaq/lib/perlfaq3.pod
index 01502c8385..4cf89c2b50 100644
--- a/cpan/perlfaq/lib/perlfaq3.pod
+++ b/cpan/perlfaq/lib/perlfaq3.pod
@@ -744,7 +744,7 @@ toward this:
 
 =over 4
 
-=item * Don't slurp!
+=item Don't slurp!
 
 Don't read an entire file into memory if you can process it line
 by line. Or more concretely, use a loop like this:
@@ -770,7 +770,7 @@ When the files you're processing are small, it doesn't much matter which
 way you do it, but it makes a huge difference when they start getting
 larger.
 
-=item * Use map and grep selectively
+=item Use map and grep selectively
 
 Remember that both map and grep expect a LIST argument, so doing this:
 
@@ -783,7 +783,7 @@ to loop:
                 push(@wanted, $_) if /pattern/;
         }
 
-=item * Avoid unnecessary quotes and stringification
+=item Avoid unnecessary quotes and stringification
 
 Don't quote large strings unless absolutely necessary:
 
@@ -815,7 +815,7 @@ or
     }
 
 
-=item * Pass by reference
+=item Pass by reference
 
 Pass arrays and hashes by reference, not by value. For one thing, it's
 the only way to pass multiple lists or hashes (or both) in a single
@@ -824,7 +824,7 @@ requires some judgement, however, because any changes will be propagated
 back to the original data. If you really want to mangle (er, modify) a
 copy, you'll have to sacrifice the memory needed to make one.
 
-=item * Tie large variables to disk
+=item Tie large variables to disk
 
 For "big" data stores (i.e. ones that exceed available memory) consider
 using one of the DB modules to store it on disk instead of in RAM. This
diff --git a/cpan/perlfaq/lib/perlfaq4.pod b/cpan/perlfaq/lib/perlfaq4.pod
index 7d431625fc..fc0813a560 100644
--- a/cpan/perlfaq/lib/perlfaq4.pod
+++ b/cpan/perlfaq/lib/perlfaq4.pod
@@ -328,23 +328,23 @@ To call a function on each integer in a (small) range, you B<can> use:
 
     my @results = map { some_func($_) } (5 .. 25);
 
-but you should be aware that the C<..> operator creates a list of
-all integers in the range. This can take a lot of memory for large
-ranges. Instead use:
+but you should be aware that in this form, the C<..> operator
+creates a list of all integers in the range, which can take a lot of
+memory for large ranges. However, the problem does not occur when
+using C<..> within a C<for> loop, because in that case the range
+operator is optimized to I<iterate> over the range, without creating
+the entire list. So
 
     my @results = ();
-    for (my $i=5; $i <= 500_005; $i++) {
+    for my $i (5 .. 500_005) {
         push(@results, some_func($i));
     }
 
-This situation has been fixed in Perl5.005. Use of C<..> in a C<for>
-loop will iterate over the range, without creating the entire range.
+or even 
 
-    for my $i (5 .. 500_005) {
-        push(@results, some_func($i));
-    }
+   push(@results, some_func($_)) for 5 .. 500_005;
 
-will not create a list of 500,000 integers.
+will not create an intermediate list of 500,000 integers.
 
 =head2 How can I output Roman numerals?
 
@@ -369,12 +369,17 @@ of Tom Phoenix, talks more about this. John von Neumann said, "Anyone
 who attempts to generate random numbers by deterministic means is, of
 course, living in a state of sin."
 
-If you want numbers that are more random than C<rand> with C<srand>
-provides, you should also check out the L<Math::TrulyRandom> module from
-CPAN. It uses the imperfections in your system's timer to generate
-random numbers, but this takes quite a while. If you want a better
-pseudorandom generator than the one that comes with your operating system,
-look at "Numerical Recipes in C" at L<http://www.nr.com/>.
+Perl relies on the underlying system for the implementation of
+C<rand> and C<srand>; on some systems, the generated numbers are 
+not random enough (especially on Windows : see 
+L<http://www.perlmonks.org/?node_id=803632>). 
+Several CPAN modules in the C<Math> namespace implement better
+pseudorandom generators; see for example 
+L<Math::Random::MT> ("Mersenne Twister", fast), or 
+L<Math::TrulyRandom> (uses the imperfections in the system's 
+timer to generate random numbers, which is rather slow).
+More algorithms for random numbers are described in 
+"Numerical Recipes in C" at L<http://www.nr.com/>
 
 =head2 How do I get a random number between X and Y?
 
@@ -711,43 +716,21 @@ which also forces scalar context.
 
 =head2 How do I find matching/nesting anything?
 
-This isn't something that can be done in one regular expression, no
-matter how complicated. To find something between two single
+To find something between two single
 characters, a pattern like C</x([^x]*)x/> will get the intervening
 bits in $1. For multiple ones, then something more like
-C</alpha(.*?)omega/> would be needed. But none of these deals with
-nested patterns. For balanced expressions using C<(>, C<{>, C<[> or
-C<< < >> as delimiters, use the CPAN module Regexp::Common, or see
-L<perlre/(??{ code })>. For other cases, you'll have to write a
-parser.
-
-If you are serious about writing a parser, there are a number of
-modules or oddities that will make your life a lot easier. There are
-the CPAN modules L<Parse::RecDescent>, L<Parse::Yapp>, and
-L<Text::Balanced>; and the C<byacc> program. Starting from perl 5.8
-the L<Text::Balanced> is part of the standard distribution.
-
-One simple destructive, inside-out approach that you might try is to
-pull out the smallest nesting parts one at a time:
-
-    while (s/BEGIN((?:(?!BEGIN)(?!END).)*)END//gs) {
-        # do something with $1
-    }
-
-A more complicated and sneaky approach is to make Perl's regular
-expression engine do it for you. This is courtesy Dean Inada, and
-rather has the nature of an Obfuscated Perl Contest entry, but it
-really does work:
-
-    # $_ contains the string to parse
-    # BEGIN and END are the opening and closing markers for the
-    # nested text.
-
-    @( = ('(','');
-    @) = (')','');
-    ($re=$_)=~s/((BEGIN)|(END)|.)/$)[!$3]\Q$1\E$([!$2]/gs;
-    @$ = (eval{/$re/},$@!~/unmatched/i);
-    print join("\n",@$[0..$#$]) if( $$[-1] );
+C</alpha(.*?)omega/> would be needed. For nested patterns
+and/or balanced expressions, see the so-called
+L<< (?PARNO)|perlre/C<(?PARNO)> C<(?-PARNO)> C<(?+PARNO)> C<(?R)> C<(?0)> >>
+construct (available since perl 5.10).
+The CPAN module L<Regexp::Common> can help to build such
+regular expressions (see in particular 
+L<Regexp::Common::balanced> and L<Regexp::Common::delimited>).
+
+More complex cases will require to write a parser, probably
+using a parsing module from CPAN, like
+L<Regexp::Grammars>, L<Parse::RecDescent>, L<Parse::Yapp>, 
+L<Text::Balanced>, or L<Marpa>. 
 
 =head2 How do I reverse a string?
 
@@ -1603,9 +1586,15 @@ same thing. Once you find the element, you stop the loop with last.
         if( /Perl/ ) { $found = $_; last }
     }
 
-If you want the array index, you can iterate through the indices
-and check the array element at each index until you find one
-that satisfies the condition.
+If you want the array index, use the C<firstidx()> function from
+C<List::MoreUtils>:
+
+    use List::MoreUtils qw(firstidx);
+    my $index = firstidx { /Perl/ } @array;
+
+Or write it yourself, iterating through the indices
+and checking the array element at each index until you find one
+that satisfies the condition:
 
     my( $found, $index ) = ( undef, -1 );
     for( $i = 0; $i < @array; $i++ ) {
@@ -2060,8 +2049,8 @@ The C<each()> operator can be a bit tricky though. You can't add or
 delete keys of the hash while you're using it without possibly
 skipping or re-processing some pairs after Perl internally rehashes
 all of the elements. Additionally, a hash has only one iterator, so if
-you use C<keys>, C<values>, or C<each> on the same hash, you can reset
-the iterator and mess up your processing. See the C<each> entry in
+you mix C<keys>, C<values>, or C<each> on the same hash, you risk resetting
+the iterator and messing up your processing. See the C<each> entry in
 L<perlfunc> for more details.
 
 =head2 How do I merge two hashes?
@@ -2539,6 +2528,12 @@ L<Data::Diver> does for you:
        return 1;
     }
 
+=head2 How can I prevent addition of unwanted keys into a hash?
+
+Since version 5.8.0, hashes can be I<restricted> to a fixed number
+of given keys. Methods for creating and dealing with restricted hashes 
+are exported by the L<Hash::Util> module.
+
 =head1 Data: Misc
 
 =head2 How do I handle binary data correctly?
@@ -2668,6 +2663,7 @@ the L<PDL> module from CPAN instead--it makes number-crunching easy.
 
 See L<http://search.cpan.org/dist/PGPLOT> for the code.
 
+
 =head1 AUTHOR AND COPYRIGHT
 
 Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and
diff --git a/cpan/perlfaq/lib/perlfaq6.pod b/cpan/perlfaq/lib/perlfaq6.pod
index 4f6c562462..40c2b07c3d 100644
--- a/cpan/perlfaq/lib/perlfaq6.pod
+++ b/cpan/perlfaq/lib/perlfaq6.pod
@@ -157,42 +157,12 @@ Here's another example of using C<..>:
 X<regex, XML> X<regex, HTML> X<XML> X<HTML> X<pain> X<frustration>
 X<sucking out, will to live>
 
-(contributed by brian d foy)
-
-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
-have done for you already! :)
-
-The problem with things such as XML is that they have balanced text
-containing multiple levels of balanced text, but sometimes it isn't
-balanced text, as in an empty tag (C<< <br/> >>, for instance). Even then,
-things can occur out-of-order. Just when you think you've got a
-pattern that matches your input, someone throws you a curveball.
-
-If you'd like to do it the hard way, scratching and clawing your way
-toward a right answer but constantly being disappointed, besieged by
-bug reports, and weary from the inordinate amount of time you have to
-spend reinventing a triangular wheel, then there are several things
-you can try before you give up in frustration:
-
-=over 4
-
-=item * Solve the balanced text problem from another question in L<perlfaq6>
-
-=item * Try the recursive regex features in Perl 5.10 and later. See L<perlre>
-
-=item * Try defining a grammar using Perl 5.10's C<(?DEFINE)> feature.
-
-=item * Break the problem down into sub-problems instead of trying to use a single regex
-
-=item * Convince everyone not to use XML or HTML in the first place
-
-=back
-
-Good luck!
+Do not use regexes. Use a module and forget about the
+regular expressions. The L<XML::LibXML>, L<HTML::TokeParser> and
+L<HTML::TreeBuilder> 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://metacpan.org/> )
+and wonder at all the work people have done for you already! :)
 
 =head2 I put a regular expression into $/ but it didn't work. What's wrong?
 X<$/, regexes in> X<$INPUT_RECORD_SEPARATOR, regexes in>
diff --git a/cpan/perlfaq/lib/perlfaq7.pod b/cpan/perlfaq/lib/perlfaq7.pod
index 293834c76d..20922f375b 100644
--- a/cpan/perlfaq/lib/perlfaq7.pod
+++ b/cpan/perlfaq/lib/perlfaq7.pod
@@ -464,7 +464,7 @@ In Perl 5.10, declare the variable with C<state>. The C<state>
 declaration creates the lexical variable that persists between calls
 to the subroutine:
 
-    sub counter { state $count = 1; $counter++ }
+    sub counter { state $count = 1; $count++ }
 
 You can fake a static variable by using a lexical variable which goes
 out of scope. In this example, you define the subroutine C<counter>, and
@@ -604,7 +604,7 @@ 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>$fh<gt>;" work right?
+=head2 Why doesn't "my($foo) = E<lt>$fhE<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
diff --git a/cpan/perlfaq/lib/perlfaq9.pod b/cpan/perlfaq/lib/perlfaq9.pod
index dc71115f1a..2a588980df 100644
--- a/cpan/perlfaq/lib/perlfaq9.pod
+++ b/cpan/perlfaq/lib/perlfaq9.pod
@@ -1,200 +1,83 @@
 =head1 NAME
 
-perlfaq9 - Networking
+perlfaq9 - Web, Email and Networking
 
 =head1 DESCRIPTION
 
-This section deals with questions related to networking, the Internet,
-and a few about the Web.
+This section deals with questions related to running web sites,
+sending and receiving email as well as general networking.
 
-=head2 What is the correct form of response from a CGI script?
+=head2 Should I use a web framework?
 
-(Alan Flavell <flavell+www@a5.ph.gla.ac.uk> answers...)
+Yes. If you are building a web site with any level of interactivity 
+(forms / users / databases), you
+will want to use a framework to make handling requests
+and responses easier.
 
-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 a Usenet group,
-comp.infosystems.www.authoring.cgi.
+If there is no interactivity then you may still want
+to look at using something like L<Template Toolkit|https://metacpan.org/module/Template>
+or L<Plack::Middleware::TemplateToolkit> 
+so maintenance of your HTML files (and other assets) is easier.
 
-The CGI specification is outlined in an informational RFC:
-L<http://www.ietf.org/rfc/rfc3875>
+=head2 Which web framework should I use?
+X<framework> X<CGI.pm> X<CGI> X<Catalyst> X<Dancer>
 
-These Perl FAQs very selectively cover some CGI issues. However, Perl
-programmers are strongly advised to use the C<CGI.pm> module, to take care
-of the details for them.
+There are many Perl web frameworks, e.g. :
 
-The similarity between CGI response headers (defined in the CGI
-specification) and HTTP response headers (defined in the HTTP
-specification, RFC2616) is intentional, but can sometimes be confusing.
-
-The CGI specification defines two kinds of script: the "Parsed Header"
-script, and the "Non Parsed Header" (NPH) script. Check your server
-documentation to see what it supports. "Parsed Header" scripts are
-simpler in various respects. The CGI specification allows any of the
-usual newline representations in the CGI response (it's the server's
-job to create an accurate HTTP response based on it). So "\n" written in
-text mode is technically correct, and recommended. NPH scripts are more
-tricky: they must put out a complete and accurate set of HTTP
-transaction response headers; the HTTP specification calls for records
-to be terminated with carriage-return and line-feed; i.e., ASCII \015\012
-written in binary mode.
-
-Using C<CGI.pm> gives excellent platform independence, including EBCDIC
-systems. C<CGI.pm> selects an appropriate newline representation
-(C<$CGI::CRLF>) and sets binmode as appropriate.
-
-=head2 My CGI script runs from the command line but not the browser. (500 Server Error)
+=over 4
 
-(contributed by brian d foy)
+=item L<Web::Simple> - A quick and easy way to build simple web applications
 
-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/>> .
+=item L<Dancer> - Lightweight yet powerful web application framework
 
-=head2 How can I get better error messages from a CGI program?
+=item L<Catalyst> - Elegant MVC Web Application Framework
 
-Use the L<CGI::Carp> module. It replaces C<warn> and C<die>, plus the
-normal L<Carp> module's C<carp>, C<croak>, and C<confess> functions with
-more verbose and safer versions. It still sends them to the normal
-server error log.
+=back
 
-    use CGI::Carp;
-    warn "This is a complaint";
-    die "But this one is serious";
+These are just a few of the more widely used ones. All of them
+interact with or use L<Plack> which is worth understanding
+the basics of, as there is a lot of useful
+L<Plack::Middleware|https://metacpan.org/search?q=plack%3A%3Amiddleware>.
 
-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:
+As to which one you should use, it depends on the complexity
+of the site you are trying to build. Review the three listed
+above and see which suites your needs best. Many of them share the
+same L<MVC|http://en.wikipedia.org/wiki/Model-view-controller>
+concepts so once you understand one it is easier to understand
+the others.
 
-    use vars qw($log_fh);
-    BEGIN {
-        use CGI::Carp qw(carpout);
-        open($log_fh, ">>/var/local/cgi-logs/mycgi-log")
-            or die "Unable to append to mycgi-log: $!\n";
-        carpout(*LOG);
-    }
+=head2 What is Plack and PSGI?
 
-You can even arrange for fatal errors to go back to the client browser,
-which is nice for your own debugging, but might confuse the end user.
+L<PSGI> is the Perl Web Server Gateway Interface Specification, it is
+a standard that many Perl web frameworks use, you should not need to 
+understand it to build a web site, the part you might want to use is L<Plack>.
 
-    use CGI::Carp qw(fatalsToBrowser);
-    die "Bad error here";
+L<Plack> is a set of tools for using the PSGI stack. It contains 
+L<middleware|https://metacpan.org/search?q=plack%3A%3Amiddleware> 
+components, a reference server and utilities for Web application frameworks. 
+Plack is like Ruby's Rack or Python's Paste for WSGI.
 
-Even if the error happens before you get the HTTP header out, the module
-will try to take care of this to avoid the dreaded server 500 errors.
-Normal warnings still go out to the server error log (or wherever
-you've sent them with C<carpout>) with the application name and date
-stamp prepended.
+You could build a web site using L<Plack> and your own code,
+but for anything other than a very basic web site, using a web framework 
+(that uses L<Plack>) is a better option.
 
 =head2 How do I remove HTML from a string?
 
-The most correct way (albeit not the fastest) is to use L<HTML::Parser>
-from CPAN. Another mostly correct
-way is to use L<HTML::FormatText> which not only removes HTML but also
-attempts to do a little simple formatting of the resulting plain text.
-
-Many folks attempt a simple-minded regular expression approach, like
-C<< s/<.*?>//g >>, but that fails in many cases because the tags
-may continue over line breaks, they may contain quoted angle-brackets,
-or HTML comments may be present. Plus, folks forget to convert
-entities--like C<&lt;> for example.
-
-Here's one "simple-minded" approach, that works for most files:
-
-    #!/usr/bin/perl -p0777
-    s/<(?:[^>'"]*|(['"]).*?\g1)*>//gs
-
-If you want a more complete solution, see the 3-stage striphtml
-program in
-L<http://www.cpan.org/authors/Tom_Christiansen/scripts/striphtml.gz>
-.
-
-Here are some tricky cases that you should think about when picking
-a solution:
-
-    <IMG SRC = "foo.gif" ALT = "A > B">
-
-    <IMG SRC = "foo.gif"
-     ALT = "A > B">
-
-    <!-- <A comment> -->
-
-    <script>if (a<b && a>c)</script>
-
-    <# Just data #>
-
-    <![INCLUDE CDATA [ >>>>>>>>>>>> ]]>
-
-If HTML comments include other tags, those solutions would also break
-on text like this:
-
-    <!-- This section commented out.
-        <B>You can't see me!</B>
-    -->
+Use L<HTML::Strip>, or L<HTML::FormatText> which not only removes HTML 
+but also attempts to do a little simple formatting of the resulting 
+plain text.
 
 =head2 How do I extract URLs?
 
-You can easily extract all sorts of URLs from HTML with
-L<HTML::SimpleLinkExtor> which handles anchors, images, objects,
-frames, and many other tags that can contain a URL. If you need
-anything more complex, you can create your own subclass of
+L<HTML::SimpleLinkExtor> will extract URLs from HTML, it handles anchors, 
+images, objects, frames, and many other tags that can contain a URL. 
+If you need anything more complex, you can create your own subclass of
 L<HTML::LinkExtor> or L<HTML::Parser>. You might even use
 L<HTML::SimpleLinkExtor> as an example for something specifically
 suited to your needs.
 
 You can use L<URI::Find> to extract URLs from an arbitrary text document.
 
-Less complete solutions involving regular expressions can save
-you a lot of processing time if you know that the input is simple. One
-solution from Tom Christiansen runs 100 times faster than most
-module-based approaches but only extracts URLs from anchors where the first
-attribute is HREF and there are no other attributes.
-
-    #!/usr/bin/perl -n00
-    # qxurl - tchrist@perl.com
-    print "$2\n" while m{
-        < \s*
-          A \s+ HREF \s* = \s* (["']) (.*?) \g1
-        \s* >
-    }gsix;
-
-=head2 How do I download a file from the user's machine? How do I open a file on another machine?
-
-In this case, download means to use the file upload feature of HTML
-forms. You allow the web surfer to specify a file to send to your web
-server. To you it looks like a download, and to the user it looks
-like an upload. No matter what you call it, you do it with what's
-known as B<multipart/form-data> encoding. The C<CGI.pm> module (which
-comes with Perl as part of the Standard Library) supports this in the
-C<start_multipart_form()> method, which isn't the same as the C<startform()>
-method.
-
-See the section in the C<CGI.pm> documentation on file uploads for code
-examples and details.
-
-=head2 How do I make an HTML pop-up menu with Perl?
-
-(contributed by brian d foy)
-
-The C<CGI.pm> module (which comes with Perl) has functions to create
-the HTML form widgets. See the C<CGI.pm> documentation for more
-examples.
-
-    use CGI qw/:standard/;
-    print header,
-        start_html('Favorite Animals'),
-
-        start_form,
-            "What's your favorite animal? ",
-        popup_menu(
-            -name   => 'animal',
-            -values => [ qw( Llama Alpaca Camel Ram ) ]
-            ),
-        submit,
-
-        end_form,
-        end_html;
-
 =head2 How do I fetch an HTML file?
 
 (contributed by brian d foy)
@@ -245,24 +128,14 @@ the content appropriately.
     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>
-
-(contributed by brian d foy)
+X<URI> X<URI::Escape> X<RFC 2396>
 
-Those C<%> encodings handle reserved characters in URIs, as described
-in RFC 2396, Section 2. This encoding replaces the reserved character
-with the hexadecimal representation of the character's number from
-the US-ASCII table. For instance, a colon, C<:>, becomes C<%3A>.
+Most of the time you should not need to do this as
+your web framework, or if you are making a request,
+the L<LWP> or other module would handle it for you.
 
-In CGI scripts, you don't have to worry about decoding URIs if you are
-using C<CGI.pm>. You shouldn't have to process the URI yourself,
-either on the way in or the way out.
-
-If you have to encode a string yourself, remember that you should
-never try to encode an already-composed URI. You need to escape the
-components separately then put them together. To encode a string, you
-can use the L<URI::Escape> module. The C<uri_escape> function
-returns the escaped string:
+To encode a string yourself, use the L<URI::Escape> module. The C<uri_escape> 
+function returns the escaped string:
 
     my $original = "Colon : Hash # Percent %";
 
@@ -276,66 +149,30 @@ To decode the string, use the C<uri_unescape> function:
 
     print $unescaped; # back to original
 
-If you wanted to do it yourself, you simply need to replace the
-reserved characters with their encodings. A global substitution
-is one way to do it:
-
-    # encode
-    $string =~ s/([^^A-Za-z0-9\-_.!~*'()])/ sprintf "%%%0x", ord $1 /eg;
-
-    #decode
-    $string =~ s/%([A-Fa-f\d]{2})/chr hex $1/eg;
+Remember not to encode a full URI, you need to escape each
+component separately and then join them together.
 
 =head2 How do I redirect to another page?
 
-Specify the complete URL of the destination (even if it is on the same
-server). This is one of the two different kinds of CGI "Location:"
-responses which are defined in the CGI specification for a Parsed Headers
-script. The other kind (an absolute URLpath) is resolved internally to
-the server without any HTTP redirection. The CGI specifications do not
-allow relative URLs in either case.
-
-Use of C<CGI.pm> is strongly recommended. This example shows redirection
-with a complete URL. This redirection is handled by the web browser.
+Most Perl Web Frameworks will have a mechanism for doing this,
+using the L<Catalyst> framework it would be:
 
-    use CGI qw/:standard/;
-
-    my $url = 'L<http://www.cpan.org/'>;
-    print redirect($url);
-
-This example shows a redirection with an absolute URLpath. This
-redirection is handled by the local web server.
-
-    my $url = '/CPAN/index.html';
-    print redirect($url);
-
-But if coded directly, it could be as follows (the final "\n" is
-shown separately, for clarity), using either a complete URL or
-an absolute URLpath.
-
-    print "Location: $url\n";   # CGI response header
-    print "\n";                 # end of headers
+    $c->res->redirect($url);
+    $c->detach();
+    
+If you are using Plack (which most frameworks do), then
+L<Plack::Middleware::Rewrite> is worth looking at if you
+are migrating from Apache or have URL's you want to always
+redirect.
 
 =head2 How do I put a password on my web pages?
 
-To enable authentication for your web server, you need to configure
-your web server. The configuration is different for different sorts
-of web servers--apache does it differently from iPlanet which does
-it differently from IIS. Check your web server documentation for
-the details for your particular server.
+See if the web framework you are using has an
+authentication system and if that fits your needs.
 
-=head2 How do I edit my .htpasswd and .htgroup files with Perl?
-
-The L<HTTPD::UserAdmin> and L<HTTPD::GroupAdmin> modules provide a
-consistent OO interface to these files, regardless of how they're
-stored. Databases may be text, dbm, Berkeley DB or any database with
-a DBI compatible driver. L<HTTPD::UserAdmin> supports files used by the
-"Basic" and "Digest" authentication schemes. Here's an example:
-
-    use HTTPD::UserAdmin ();
-    HTTPD::UserAdmin
-      ->new(DB => "/foo/.htpasswd")
-      ->add($username => $password);
+Alternativly look at L<Plack::Middleware::Auth::Basic>,
+or one of the other L<Plack authentication|https://metacpan.org/search?q=plack+auth>
+options.
 
 =head2 How do I make sure users can't enter values into a form that causes my CGI script to do bad things?
 
@@ -344,7 +181,7 @@ a DBI compatible driver. L<HTTPD::UserAdmin> supports files used by the
 You can't prevent people from sending your script bad data. Even if
 you add some client-side checks, people may disable them or bypass
 them completely. For instance, someone might use a module such as
-L<LWP> to access your CGI program. If you want to prevent data that
+L<LWP> to submit to your web site. If you want to prevent data that
 try to use SQL injection or other sorts of attacks (and you should
 want to), you have to not trust any data that enter your program.
 
@@ -375,45 +212,6 @@ L<Email::MIME> object:
   my $abstract = Email::Abstract->new($mail_message_object);
   my $email_mime_object = $abstract->cast('Email::MIME');
 
-=head2 How do I decode a CGI form?
-
-(contributed by brian d foy)
-
-Use the C<CGI.pm> module that comes with Perl. It's quick,
-it's easy, and it actually does quite a bit of work to
-ensure things happen correctly. It handles GET, POST, and
-HEAD requests, multipart forms, multivalued fields, query
-string and message body combinations, and many other things
-you probably don't want to think about.
-
-It doesn't get much easier: the C<CGI.pm> module automatically
-parses the input and makes each value available through the
-C<param()> function.
-
-    use CGI qw(:standard);
-
-    my $total = param( 'price' ) + param( 'shipping' );
-
-    my @items = param( 'item' ); # multiple values, same field name
-
-If you want an object-oriented approach, C<CGI.pm> can do that too.
-
-    use CGI;
-
-    my $cgi = CGI->new();
-
-    my $total = $cgi->param( 'price' ) + $cgi->param( 'shipping' );
-
-    my @items = $cgi->param( 'item' );
-
-You might also try L<CGI::Minimal> which is a lightweight version
-of the same thing. Other CGI::* modules on CPAN might work better
-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 of a hassle to use C<CGI.pm>.
-
 =head2 How do I check a valid mail address?
 
 (partly contributed by Aaron Sherman)
@@ -455,22 +253,6 @@ Decoding base 64 becomes as simple as:
 The L<Email::MIME> module can decode base 64-encoded email message parts
 transparently so the developer doesn't need to worry about it.
 
-=head2 How do I return the user's mail address?
-
-Ask them for it. There are so many email providers available that it's
-rather unlikely the local system has any idea how to determine a user's
-email address. The one notable exception is for organization-specific
-email (e.g. foo@yourcompany.com) where policy can be codified in your
-program. In that case, you can look at $ENV{USER}, $ENV{LOGNAME}, and
-getpwuid($<) in scalar context, like so:
-
-  my $user_name = getpwuid($<)
-
-But note that you still cannot make any assumptions about whether this
-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 email?
 
 Use the L<Email::MIME> and L<Email::Sender::Simple> modules, like so:
@@ -587,36 +369,14 @@ from the L<Socket> module, which also comes with perl.
         scalar gethostbyname( $host || 'localhost' )
     );
 
-=head2 How do I fetch a news article or the active newsgroups?
-
-Use the L<Net::NNTP> or L<News::NNTPClient> modules, both available from CPAN.
-This can make tasks like fetching the newsgroup list as simple as
-
-    perl -MNews::NNTPClient
-      -e 'print News::NNTPClient->new->list("newsgroups")'
+=head2 How do I fetch/put an (S)FTP file?
 
-=head2 How do I fetch/put an FTP file?
-
-(contributed by brian d foy)
-
-The L<LWP> family of modules (available on CPAN as the libwww-perl distribution)
-can work with FTP just like it can with many other protocols. L<LWP::Simple>
-makes it quite easy to fetch a file:
-
-    use LWP::Simple;
-
-    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). Its
-documentation has examples showing you just how to do that.
+L<Net::FTP>, and L<Net::SFTP> allow you to interact with FTP and SFTP (Secure
+FTP) servers.
 
 =head2 How can I do RPC in Perl?
 
-(contributed by brian d foy)
-
-Use one of the RPC modules you can find on CPAN (
-L<http://search.cpan.org/search?query=RPC&mode=all> ).
+Use one of the RPC modules( L<https://metacpan.org/search?q=RPC> ).
 
 =head1 AUTHOR AND COPYRIGHT
 
diff --git a/cpan/perlfaq/lib/perlglossary.pod b/cpan/perlfaq/lib/perlglossary.pod
index 94ce6d52df..d6359f9e22 100644
--- a/cpan/perlfaq/lib/perlglossary.pod
+++ b/cpan/perlfaq/lib/perlglossary.pod
@@ -1362,7 +1362,8 @@ you can easily use a string L</key> to look up its associated data
 L</value>.  This glossary is like a hash, where the word to be defined
 is the key, and the definition is the value.  A hash is also sometimes
 septisyllabically called an "associative array", which is a pretty
-good reason for simply calling it a "hash" instead.
+good reason for simply calling it a "hash" instead. A hash can optionally
+be L<restricted|/restricted hash> to a fixed set of keys.
 
 =item hash table
 
@@ -2527,6 +2528,10 @@ why they're reserved, after all.)  In Perl, you just can't use them to
 name L<labels|/label> or L<filehandles|/filehandle>.  Also called
 "keywords".
 
+=item restricted hash
+
+A L</hash> with a closed set of allowed keys. See L<Hash::Util>.
+
 =item return value
 
 The L</value> produced by a L</subroutine> or L</expression> when