Upgrade perlfaq from version 5.0150043 to 5.0150044

9 files changed, 117 insertions, 43 deletions

diff --git a/cpan/perlfaq/lib/perlfaq.pm b/cpan/perlfaq/lib/perlfaq.pm
index 907a1992c2..6d6a05a75e 100644
--- a/cpan/perlfaq/lib/perlfaq.pm
+++ b/cpan/perlfaq/lib/perlfaq.pm
@@ -1,6 +1,6 @@
 package perlfaq;
 {
-  $perlfaq::VERSION = '5.0150043';
+  $perlfaq::VERSION = '5.0150044';
 }
 
 0; # not is it supposed to be loaded
diff --git a/cpan/perlfaq/lib/perlfaq.pod b/cpan/perlfaq/lib/perlfaq.pod
index dff90c964d..834351eddf 100644
--- a/cpan/perlfaq/lib/perlfaq.pod
+++ b/cpan/perlfaq/lib/perlfaq.pod
@@ -97,6 +97,10 @@ How stable is Perl?
 
 =item *
 
+How often are new versions of Perl released?
+
+=item *
+
 Is Perl difficult to learn?
 
 =item *
@@ -1049,6 +1053,10 @@ How can I use a variable as a variable name?
 
 What does "bad interpreter" mean?
 
+=item *
+
+Do I need to recompile XS modules when there is a change in the C library?
+
 =back
 
 
@@ -1256,6 +1264,10 @@ How do I add a directory to my include path (@INC) at runtime?
 
 =item *
 
+Where are modules installed?
+
+=item *
+
 What is socket.ph and where do I get it?
 
 =back
diff --git a/cpan/perlfaq/lib/perlfaq1.pod b/cpan/perlfaq/lib/perlfaq1.pod
index a02fae6a70..19eb1edb77 100644
--- a/cpan/perlfaq/lib/perlfaq1.pod
+++ b/cpan/perlfaq/lib/perlfaq1.pod
@@ -59,7 +59,7 @@ users the informal support will more than suffice. See the answer to
 There is often a matter of opinion and taste, and there isn't any one
 answer that fits everyone. In general, you want to use either the current
 stable release, or the stable release immediately prior to that one.
-Currently, those are perl5.14.x and perl5.12.x, respectively.
+Currently, those are perl5.18.x and perl5.16.x, respectively.
 
 Beyond that, you have to consider several things and decide which is best
 for you.
@@ -94,7 +94,7 @@ problems others have if you are risk averse.
 
 =item *
 
-The immediate, previous releases (i.e. perl5.8.x ) are usually maintained
+The immediate, previous releases (i.e. perl5.14.x ) are usually maintained
 for a while, although not at the same level as the current releases.
 
 =item *
@@ -113,10 +113,10 @@ usable, 'early adopter'" distribution of Perl 6 (called Rakudo Star) in July of
 
 There are really two tracks of perl development: a maintenance version
 and an experimental version. The maintenance versions are stable, and
-have an even number as the minor release (i.e. perl5.10.x, where 10 is the
+have an even number as the minor release (i.e. perl5.18.x, where 18 is the
 minor release). The experimental versions may include features that
 don't make it into the stable versions, and have an odd number as the
-minor release (i.e. perl5.9.x, where 9 is the minor release).
+minor release (i.e. perl5.19.x, where 9 is the minor release).
 
 =back
 
@@ -174,6 +174,23 @@ The Perl development team occasionally make changes to the
 internal core of the language, but all possible efforts are made toward
 backward compatibility.
 
+=head2 How often are new versions of Perl released?
+
+Recently, the plan has been to release a new version of Perl roughly every
+April, but getting the release right is more important than sticking rigidly to
+a calendar date, so the release date is somewhat flexible.  The historical
+release dates can be viewed at L<http://www.cpan.org/src/README.html>.
+
+Even numbered minor versions (5.14, 5.16, 5.18) are production versions, and
+odd numbered minor versions (5.15, 5.17, 5.19) are development versions. Unless
+you want to try out an experimental feature, you probably never want to install
+a development version of Perl.
+
+The Perl development team are called Perl 5 Porters, and their
+organization is described at L<http://perldoc.perl.org/perlpolicy.html>.
+The organizational rules really just boil down to one: Larry is always
+right, even when he was wrong.
+
 =head2 Is Perl difficult to learn?
 
 No, Perl is easy to start L<learning|http://learn.perl.org/> --and easy to keep learning. It looks
diff --git a/cpan/perlfaq/lib/perlfaq3.pod b/cpan/perlfaq/lib/perlfaq3.pod
index 7fc7e75721..46de630fdf 100644
--- a/cpan/perlfaq/lib/perlfaq3.pod
+++ b/cpan/perlfaq/lib/perlfaq3.pod
@@ -370,8 +370,9 @@ the tool runs on Windows 9x/NT/2000/XP or later.
 
 L<http://kephra.sf.net>
 
-GUI Editor written in Perl using wxWidgets and Scintilla with lots of smaller features.
-Aims for an UI based on Perls principles like TIMTWTDI and "easy things should be ..".
+GUI editor written in Perl using wxWidgets and Scintilla with lots of smaller features.
+Aims for a UI based on Perl principles like TIMTOWTDI and "easy things should be easy,
+hard things should be possible".
 
 =item Komodo
 
@@ -1097,8 +1098,8 @@ simple CGI scripts.
 
 =head2 Where can I learn about object-oriented Perl programming?
 
-A good place to start is L<perltoot>, and you can use L<perlobj>,
-L<perlboot>, L<perltoot>, L<perltooc>, and L<perlbot> for reference.
+A good place to start is L<perlootut>, and you can use L<perlobj> for
+reference.
 
 A good book on OO on Perl is the "Object-Oriented Perl"
 by Damian Conway from Manning Publications, or "Intermediate Perl"
diff --git a/cpan/perlfaq/lib/perlfaq4.pod b/cpan/perlfaq/lib/perlfaq4.pod
index 72607f3691..f615bf4bf9 100644
--- a/cpan/perlfaq/lib/perlfaq4.pod
+++ b/cpan/perlfaq/lib/perlfaq4.pod
@@ -2430,7 +2430,7 @@ Usually a hash ref, perhaps like this:
 References are documented in L<perlref> and L<perlreftut>.
 Examples of complex data structures are given in L<perldsc> and
 L<perllol>. Examples of structures and object-oriented classes are
-in L<perltoot>.
+in L<perlootut>.
 
 =head2 How can I use a reference as a hash key?
 
diff --git a/cpan/perlfaq/lib/perlfaq7.pod b/cpan/perlfaq/lib/perlfaq7.pod
index 12c25ef399..bd6c102dae 100644
--- a/cpan/perlfaq/lib/perlfaq7.pod
+++ b/cpan/perlfaq/lib/perlfaq7.pod
@@ -174,7 +174,7 @@ Here's an example:
     $person->{AGE}  = 24;           # set field AGE to 24
     $person->{NAME} = "Nat";        # set field NAME to "Nat"
 
-If you're looking for something a bit more rigorous, try L<perltoot>.
+If you're looking for something a bit more rigorous, try L<perlootut>.
 
 =head2 How do I create a module?
 
@@ -189,8 +189,8 @@ to automate as much as possible.
 Detailed documentation about modules can be found at:
 L<perlmod>, L<perlmodlib>, L<perlmodstyle>.
 
-If you need to include C code or C library interfaces 
-use h2xs. h2xs will create the module distribution structure 
+If you need to include C code or C library interfaces
+use h2xs. h2xs will create the module distribution structure
 and the initial interface files.
 L<perlxs> and L<perlxstut> explain the details.
 
@@ -240,10 +240,7 @@ Perl doesn't get more formal than that and lets you set up the package
 just the way that you like it (that is, it doesn't set up anything for
 you).
 
-The Perl documentation has several tutorials that cover class
-creation, including L<perlboot> (Barnyard Object Oriented Tutorial),
-L<perltoot> (Tom's Object Oriented Tutorial), L<perlbot> (Bag o'
-Object Tricks), and L<perlobj>.
+See also L<perlootut>, a tutorial that covers class creation, and L<perlobj>.
 
 =head2 How can I tell if a variable is tainted?
 
@@ -633,7 +630,7 @@ then you'll want to use the C<use overload> pragma, documented
 in L<overload>.
 
 If you're talking about obscuring method calls in parent classes,
-see L<perltoot/"Overridden Methods">.
+see L<perlootut/"Overriding methods and method resolution">.
 
 =head2 What's the difference between calling a function as &foo and foo()?
 
@@ -644,30 +641,50 @@ the prototype of C<foo> and passes it the current value of the argument
 list, C<@_>. Here's an example; the C<bar> subroutine calls C<&foo>,
 which prints its arguments list:
 
-    sub bar { &foo }
+    sub foo { print "Args in foo are: @_\n"; }
 
-    sub foo { print "Args in foo are: @_\n" }
+    sub bar { &foo; }
 
-    bar( qw( a b c ) );
+    bar( "a", "b", "c" );
 
 When you call C<bar> with arguments, you see that C<foo> got the same C<@_>:
 
     Args in foo are: a b c
 
 Calling the subroutine with trailing parentheses, with or without arguments,
-does not use the current C<@_> and respects the subroutine prototype. Changing
-the example to put parentheses after the call to C<foo> changes the program:
+does not use the current C<@_>. Changing the example to put parentheses after
+the call to C<foo> changes the program:
 
-    sub bar { &foo() }
+    sub foo { print "Args in foo are: @_\n"; }
 
-    sub foo { print "Args in foo are: @_\n" }
+    sub bar { &foo(); }
 
-    bar( qw( a b c ) );
+    bar( "a", "b", "c" );
 
 Now the output shows that C<foo> doesn't get the C<@_> from its caller.
 
     Args in foo are:
 
+However, using C<&> in the call still overrides the prototype of C<foo> if
+present:
+
+    sub foo ($$$) { print "Args infoo are: @_\n"; }
+
+    sub bar_1 { &foo; }
+    sub bar_2 { &foo(); }
+    sub bar_3 { foo( $_[0], $_[1], $_[2] ); }
+    # sub bar_4 { foo(); }
+    # bar_4 doesn't compile: "Not enough arguments for main::foo at ..."
+
+    bar_1( "a", "b", "c" );
+    # Args in foo are: a b c
+
+    bar_2( "a", "b", "c" );
+    # Args in foo are:
+
+    bar_3( "a", "b", "c" );
+    # Args in foo are: a b c
+
 The main use of the C<@_> pass-through feature is to write subroutines
 whose main job it is to call other subroutines for you. For further
 details, see L<perlsub>.
@@ -772,9 +789,8 @@ when complex syntax is involved.
 
 =head2 How can I catch accesses to undefined variables, functions, or methods?
 
-The AUTOLOAD method, discussed in L<perlsub/"Autoloading"> and
-L<perltoot/"AUTOLOAD: Proxy Methods">, lets you capture calls to
-undefined functions and methods.
+The AUTOLOAD method, discussed in L<perlsub/"Autoloading"> lets you capture
+calls to undefined functions and methods.
 
 When it comes to undefined variables that would trigger a warning
 under C<use warnings>, you can promote the warning to an error.
@@ -785,7 +801,7 @@ under C<use warnings>, you can promote the warning to an error.
 
 Some possible reasons: your inheritance is getting confused, you've
 misspelled the method name, or the object is of the wrong type. Check
-out L<perltoot> for details about any of the above cases. You may
+out L<perlootut> for details about any of the above cases. You may
 also use C<print ref($object)> to find out the class C<$object> was
 blessed into.
 
@@ -1046,9 +1062,17 @@ If you get a message like "perl: command not found", perl is not in
 your PATH, which might also mean that the location of perl is not
 where you expect it so you need to adjust your shebang line.
 
+=head2 Do I need to recompile XS modules when there is a change in the C library?
+
+(contributed by Alex Beamish)
+
+If the new version of the C library is ABI-compatible (that's Application
+Binary Interface compatible) with the version you're upgrading from, and if the
+shared library version didn't change, no re-compilation should be necessary.
+
 =head1 AUTHOR AND COPYRIGHT
 
-Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and
+Copyright (c) 1997-2013 Tom Christiansen, Nathan Torkington, and
 other authors as noted. All rights reserved.
 
 This documentation is free; you can redistribute it and/or modify it
diff --git a/cpan/perlfaq/lib/perlfaq8.pod b/cpan/perlfaq/lib/perlfaq8.pod
index fd9b20138b..a8f16cb26b 100644
--- a/cpan/perlfaq/lib/perlfaq8.pod
+++ b/cpan/perlfaq/lib/perlfaq8.pod
@@ -654,9 +654,9 @@ To capture a program's STDOUT, but discard its STDERR:
 
     use IPC::Open3;
     use File::Spec;
-    use Symbol qw(gensym);
+    my $in = '';
     open(NULL, ">", File::Spec->devnull);
-    my $pid = open3(gensym, \*PH, ">&NULL", "cmd");
+    my $pid = open3($in, \*PH, ">&NULL", "cmd");
     while( <PH> ) { }
     waitpid($pid, 0);
 
@@ -664,17 +664,17 @@ To capture a program's STDERR, but discard its STDOUT:
 
     use IPC::Open3;
     use File::Spec;
-    use Symbol qw(gensym);
+    my $in = '';
     open(NULL, ">", File::Spec->devnull);
-    my $pid = open3(gensym, ">&NULL", \*PH, "cmd");
+    my $pid = open3($in, ">&NULL", \*PH, "cmd");
     while( <PH> ) { }
     waitpid($pid, 0);
 
 To capture a program's STDERR, and let its STDOUT go to our own STDERR:
 
     use IPC::Open3;
-    use Symbol qw(gensym);
-    my $pid = open3(gensym, ">&STDERR", \*PH, "cmd");
+    my $in = '';
+    my $pid = open3($in, ">&STDERR", \*PH, "cmd");
     while( <PH> ) { }
     waitpid($pid, 0);
 
@@ -683,11 +683,11 @@ redirect them to temp files, let the command run, then read the temp
 files:
 
     use IPC::Open3;
-    use Symbol qw(gensym);
     use IO::File;
+    my $in = '';
     local *CATCHOUT = IO::File->new_tmpfile;
     local *CATCHERR = IO::File->new_tmpfile;
-    my $pid = open3(gensym, ">&CATCHOUT", ">&CATCHERR", "cmd");
+    my $pid = open3($in, ">&CATCHOUT", ">&CATCHERR", "cmd");
     waitpid($pid, 0);
     seek $_, 0, 0 for \*CATCHOUT, \*CATCHERR;
     while( <CATCHOUT> ) {}
@@ -697,10 +697,10 @@ But there's no real need for B<both> to be tempfiles... the following
 should work just as well, without deadlocking:
 
     use IPC::Open3;
-    use Symbol qw(gensym);
+    my $in = '';
     use IO::File;
     local *CATCHERR = IO::File->new_tmpfile;
-    my $pid = open3(gensym, \*CATCHOUT, ">&CATCHERR", "cmd");
+    my $pid = open3($in, \*CATCHOUT, ">&CATCHERR", "cmd");
     while( <CATCHOUT> ) {}
     waitpid($pid, 0);
     seek CATCHERR, 0, 0;
@@ -1400,6 +1400,26 @@ The last is particularly useful because it knows about machine-dependent
 architectures. The C<lib.pm> pragmatic module was first
 included with the 5.002 release of Perl.
 
+=head2 Where are modules installed?
+
+Modules are installed on a case-by-case basis (as provided by the methods
+described in the previous section), and in the operating system. All of these
+paths are stored in @INC, which you can display with the one-liner
+
+    perl -e 'print join("\n",@INC,"")'
+
+The same information is displayed at the end of the output from the command
+
+    perl -V
+
+To find out where a module's source code is located, use
+
+    perldoc -l Encode
+
+to display the path to the module. In some cases (for example, the C<AutoLoader>
+module), this command will show the path to a separate C<pod> file; the module
+itself should be in the same directory, with a 'pm' file extension.
+
 =head2 What is socket.ph and where do I get it?
 
 It's a Perl 4 style file defining values for system networking
diff --git a/cpan/perlfaq/lib/perlfaq9.pod b/cpan/perlfaq/lib/perlfaq9.pod
index 41b9f066b2..f844e3109c 100644
--- a/cpan/perlfaq/lib/perlfaq9.pod
+++ b/cpan/perlfaq/lib/perlfaq9.pod
@@ -26,7 +26,7 @@ There is no simple answer to this question. Perl frameworks can run everything
 from basic file servers and small scale intranets to massive multinational
 multilingual websites that are the core to international businesses.
 
-Below is a list of a few frameworks with comments which might help you in 
+Below is a list of a few frameworks with comments which might help you in
 making a decision, depending on your specific requirements. Start by reading
 the docs, then ask questions on the relevant mailing list or IRC channel.
 
diff --git a/cpan/perlfaq/lib/perlglossary.pod b/cpan/perlfaq/lib/perlglossary.pod
index 6d6f280c2b..54096f72fe 100644
--- a/cpan/perlfaq/lib/perlglossary.pod
+++ b/cpan/perlfaq/lib/perlglossary.pod
@@ -2576,7 +2576,7 @@ incoming B<pipe>. See also B<C preprocessor>.
 
 =item primary maintainer
 
-The X<primary maintainer>author that PAUSE allows to assign B<co-maintainer> 
+The X<primary maintainer>author that PAUSE allows to assign B<co-maintainer>
 permissions to a B<namespace>. A primary maintainer can give up this
 distinction by assigning it to another PAUSE author. See Camel chapter 19,
 “CPAN”.