Sync perlfaq.

p4raw-id: //depot/perl@26601

10 files changed, 84 insertions, 65 deletions

diff --git a/pod/perlfaq.pod b/pod/perlfaq.pod
index 57d26b26fc..bb1935e3dc 100644
--- a/pod/perlfaq.pod
+++ b/pod/perlfaq.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq - frequently asked questions about Perl ($Date: 2005/11/10 00:36:18 $)
+perlfaq - frequently asked questions about Perl ($Date: 2005/12/30 15:04:07 $)
 
 =head1 DESCRIPTION
 
@@ -45,7 +45,7 @@ Several people have contributed answers, corrections, and comments.
 
 =head1 Author and Copyright Information
 
-Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and 
+Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and
 other contributors noted in the answers.
 
 All rights reserved.
diff --git a/pod/perlfaq1.pod b/pod/perlfaq1.pod
index dacc2f2df5..5c10f9cd75 100644
--- a/pod/perlfaq1.pod
+++ b/pod/perlfaq1.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq1 - General Questions About Perl ($Revision: 1.18 $, $Date: 2005/04/01 16:15:25 $)
+perlfaq1 - General Questions About Perl ($Revision: 1.19 $, $Date: 2005/12/31 00:54:37 $)
 
 =head1 DESCRIPTION
 
@@ -395,7 +395,7 @@ but the most recommendable way is to upgrade to at least Perl 5.6.1.
 
 =head1 AUTHOR AND COPYRIGHT
 
-Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and
+Copyright (c) 1997-2006 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/pod/perlfaq2.pod b/pod/perlfaq2.pod
index 0fd1d26253..ac34be2c01 100644
--- a/pod/perlfaq2.pod
+++ b/pod/perlfaq2.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.35 $, $Date: 2005/10/13 19:43:13 $)
+perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.38 $, $Date: 2005/12/31 00:54:37 $)
 
 =head1 DESCRIPTION
 
@@ -351,9 +351,19 @@ Recommended books on (or mostly on) Perl follow.
 
 =item Special Topics
 
+	Perl Best Practices
+	by Damian Conway
+	ISBN: 0-596-00173-8 [1st edition July 2005]
+	http://www.oreilly.com/catalog/perlbp/
+
+	Higher Order Perl
+	by Mark-Jason Dominus
+	ISBN: 1558607013 [1st edition March 2005]
+	http://hop.perl.plover.com/
+
 	Perl 6 Now: The Core Ideas Illustrated with Perl 5
 	by Scott Walters
-	ISBN 1-59059-395-2 [1st edition December 2004
+	ISBN 1-59059-395-2 [1st edition December 2004]
 	http://apress.com/book/bookDisplay.html?bID=355
 
 	Mastering Regular Expressions
@@ -516,7 +526,7 @@ the I<What is CPAN?> question earlier in this document.
 
 =head1 AUTHOR AND COPYRIGHT
 
-Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and
+Copyright (c) 1997-2006 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/pod/perlfaq3.pod b/pod/perlfaq3.pod
index 6e2f331fb7..9f1f5a6f2f 100644
--- a/pod/perlfaq3.pod
+++ b/pod/perlfaq3.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq3 - Programming Tools ($Revision: 1.54 $, $Date: 2005/11/17 17:22:02 $)
+perlfaq3 - Programming Tools ($Revision: 1.56 $, $Date: 2005/12/31 00:54:37 $)
 
 =head1 DESCRIPTION
 
@@ -85,11 +85,11 @@ with File::Find which is part of the standard library.
     my @files;
 
     find(
-      sub { 
-      	push @files, $File::Find::name 
-      		if -f $File::Find::name && /\.pm$/ 
+      sub {
+      	push @files, $File::Find::name
+      		if -f $File::Find::name && /\.pm$/
       	},
-      	
+
       @INC
       );
 
@@ -941,7 +941,7 @@ solved their problems.
 
 You might not need all the power of XS. The Inline::C module lets
 you put C code directly in your Perl source. It handles all the
-magic to make it work. You still have to learn at least some of 
+magic to make it work. You still have to learn at least some of
 the perl API but you won't have to deal with the complexity of the
 XS support files.
 
@@ -977,7 +977,7 @@ information, see L<ExtUtils::MakeMaker>.
 
 =head1 AUTHOR AND COPYRIGHT
 
-Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and
+Copyright (c) 1997-2006 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/pod/perlfaq4.pod b/pod/perlfaq4.pod
index a8d7dad783..22ea1ae581 100644
--- a/pod/perlfaq4.pod
+++ b/pod/perlfaq4.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq4 - Data Manipulation ($Revision: 1.71 $, $Date: 2005/11/23 07:46:45 $)
+perlfaq4 - Data Manipulation ($Revision: 1.73 $, $Date: 2005/12/31 00:54:37 $)
 
 =head1 DESCRIPTION
 
@@ -484,20 +484,20 @@ Use one of the Date modules. The C<DateTime> module makes it simple, and
 give you the same time of day, only the day before.
 
 	use DateTime;
-	
+
 	my $yesterday = DateTime->now->subtract( days => 1 );
-	
+
 	print "Yesterday was $yesterday\n";
 
 You can also use the C<Date::Calc> module using its Today_and_Now
 function.
 
 	use Date::Calc qw( Today_and_Now Add_Delta_DHMS );
-	
+
 	my @date_time = Add_Delta_DHMS( Today_and_Now(), -1, 0, 0, 0 );
-	
+
 	print "@date\n";
-	
+
 Most people try to use the time rather than the calendar to figure out
 dates, but that assumes that days are twenty-four hours each.  For
 most people, there are two days a year when they aren't: the switch to
@@ -589,11 +589,11 @@ does not show up next to itself
 
 This is documented in L<perlref>, and although it's not the easiest
 thing to read, it does work. In each of these examples, we call the
-function inside the braces of used to dereference a reference. If we
+function inside the braces used to dereference a reference. If we
 have a more than one return value, we can construct and dereference an
 anonymous array. In this case, we call the function in list context.
 
-    print "The time values are @{ [localtime] }.\n";
+	print "The time values are @{ [localtime] }.\n";
 
 If we want to call the function in scalar context, we have to do a bit
 more work. We can really have any code we like inside the braces, so
@@ -601,18 +601,26 @@ we simply have to end with the scalar reference, although how you do
 that is up to you, and you can use code inside the braces.
 
 	print "The time is ${\(scalar localtime)}.\n"
-	
+
 	print "The time is ${ my $x = localtime; \$x }.\n";
-	
+
 If your function already returns a reference, you don't need to create
 the reference yourself.
 
 	sub timestamp { my $t = localtime; \$t }
-	
+
 	print "The time is ${ timestamp() }.\n";
-	
-In most cases, it is probably easier to simply use string
-concatenation, which also forces scalar context.
+
+The C<Interpolation> module can also do a lot of magic for you. You can
+specify a variable name, in this case C<E>, to set up a tied hash that
+does the interpolation for you. It has several other methods to do this
+as well.
+
+	use Interpolation E => 'eval';
+	print "The time values are $E{localtime()}.\n";
+
+In most cases, it is probably easier to simply use string concatenation,
+which also forces scalar context.
 
 	print "The time is " . localtime . ".\n";
 
@@ -1277,7 +1285,7 @@ If you want to actually extract the matching elements, simply use grep in
 list context.
 
 	my @matches = grep $_ eq $whatever, @array;
-	
+
 =head2 How do I compute the difference of two arrays?  How do I compute the intersection of two arrays?
 
 Use a hash.  Here's code to do both and more.  It assumes that
@@ -1795,25 +1803,25 @@ in ASCIIbetical order. Once we have the keys, we can go through them to
 create a report which lists the keys in ASCIIbetical order.
 
 	my @keys = sort { $a cmp $b } keys %hash;
-	
+
 	foreach my $key ( @keys )
 		{
 		printf "%-20s %6d\n", $key, $hash{$value};
 		}
 
-We could get more fancy in the C<sort()> block though. Instead of 
+We could get more fancy in the C<sort()> block though. Instead of
 comparing the keys, we can compute a value with them and use that
-value as the comparison.  
+value as the comparison.
 
 For instance, to make our report order case-insensitive, we use
-the C<\L> sequence in a double-quoted string to make everything 
+the C<\L> sequence in a double-quoted string to make everything
 lowercase. The C<sort()> block then compares the lowercased
 values to determine in which order to put the keys.
 
 	my @keys = sort { "\L$a" cmp "\L$b" } keys %hash;
-	
+
 Note: if the computation is expensive or the hash has many elements,
-you may want to look at the Schwartzian Transform to cache the 
+you may want to look at the Schwartzian Transform to cache the
 computation results.
 
 If we want to sort by the hash value instead, we use the hash key
@@ -1825,8 +1833,8 @@ are ordered by their value.
 From there we can get more complex. If the hash values are the same,
 we can provide a secondary sort on the hash key.
 
-	my @keys = sort { 
-		$hash{$a} <=> $hash{$b} 
+	my @keys = sort {
+		$hash{$a} <=> $hash{$b}
 			or
 		"\L$a" cmp "\L$b"
 		} keys %hash;
@@ -2147,7 +2155,7 @@ the PDL module from CPAN instead--it makes number-crunching easy.
 
 =head1 AUTHOR AND COPYRIGHT
 
-Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and
+Copyright (c) 1997-2006 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/pod/perlfaq5.pod b/pod/perlfaq5.pod
index f5bd675683..839234e03c 100644
--- a/pod/perlfaq5.pod
+++ b/pod/perlfaq5.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq5 - Files and Formats ($Revision: 1.40 $, $Date: 2005/11/10 16:06:07 $)
+perlfaq5 - Files and Formats ($Revision: 1.42 $, $Date: 2005/12/31 00:54:37 $)
 
 =head1 DESCRIPTION
 
@@ -516,7 +516,7 @@ only version of open() and so it is prevalent in old code and books.
 Unless you have a particular reason to use the two argument form you
 should use the three argument form of open() which does not treat any
 charcters in the filename as special.
-     
+
 	open FILE, "<", "  file  ";  # filename is "   file   "
 	open FILE, ">", ">file";     # filename is ">file"
 
@@ -1106,7 +1106,7 @@ If your array contains lines, just print them:
 
 =head1 AUTHOR AND COPYRIGHT
 
-Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and
+Copyright (c) 1997-2006 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/pod/perlfaq6.pod b/pod/perlfaq6.pod
index 3cfeadf45d..72c26092ad 100644
--- a/pod/perlfaq6.pod
+++ b/pod/perlfaq6.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq6 - Regular Expressions ($Revision: 1.36 $, $Date: 2005/10/13 19:49:13 $)
+perlfaq6 - Regular Expressions ($Revision: 1.38 $, $Date: 2005/12/31 00:54:37 $)
 
 =head1 DESCRIPTION
 
@@ -873,9 +873,9 @@ a valid regular expression, trap the exception this way:
 
     if (eval { $line =~ /$pattern/ }) { }
 
-If all you really want to search for a string, not a pattern,
+If all you really want is to search for a string, not a pattern,
 then you should either use the index() function, which is made for
-string searching, or if you can't be disabused of using a pattern
+string searching, or, if you can't be disabused of using a pattern
 match on a non-pattern, then be sure to use C<\Q>...C<\E>, documented
 in L<perlre>.
 
@@ -889,7 +889,7 @@ in L<perlre>.
 
 =head1 AUTHOR AND COPYRIGHT
 
-Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and
+Copyright (c) 1997-2006 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/pod/perlfaq7.pod b/pod/perlfaq7.pod
index bb4eef8157..3933f57940 100644
--- a/pod/perlfaq7.pod
+++ b/pod/perlfaq7.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq7 - General Perl Language Issues ($Revision: 1.27 $, $Date: 2005/10/28 17:38:32 $)
+perlfaq7 - General Perl Language Issues ($Revision: 1.28 $, $Date: 2005/12/31 00:54:37 $)
 
 =head1 DESCRIPTION
 
@@ -962,7 +962,7 @@ where you expect it so you need to adjust your shebang line.
 
 =head1 AUTHOR AND COPYRIGHT
 
-Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and
+Copyright (c) 1997-2006 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/pod/perlfaq8.pod b/pod/perlfaq8.pod
index f9f3584089..55c3cbf899 100644
--- a/pod/perlfaq8.pod
+++ b/pod/perlfaq8.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq8 - System Interaction ($Revision: 1.25 $, $Date: 2005/06/04 04:12:40 $)
+perlfaq8 - System Interaction ($Revision: 1.27 $, $Date: 2005/12/31 00:54:37 $)
 
 =head1 DESCRIPTION
 
@@ -35,25 +35,26 @@ How you access/control keyboards, screens, and pointing devices
 
 =item Keyboard
 
-    Term::Cap			Standard perl distribution
-    Term::ReadKey		CPAN
-    Term::ReadLine::Gnu		CPAN
-    Term::ReadLine::Perl	CPAN
-    Term::Screen		CPAN
+	Term::Cap               Standard perl distribution
+	Term::ReadKey           CPAN
+	Term::ReadLine::Gnu     CPAN
+	Term::ReadLine::Perl    CPAN
+	Term::Screen            CPAN
 
 =item Screen
 
-    Term::Cap			Standard perl distribution
-    Curses			CPAN
-    Term::ANSIColor		CPAN
+	Term::Cap               Standard perl distribution
+	Curses                  CPAN
+	Term::ANSIColor         CPAN
 
 =item Mouse
 
-    Tk				CPAN
+	Tk                      CPAN
 
 =back
 
-Some of these specific cases are shown below.
+Some of these specific cases are shown as examples in other answers
+in this section of the perlfaq.
 
 =head2 How do I print something out in color?
 
@@ -1252,7 +1253,7 @@ but other times it is not.  Modern programs C<use Socket;> instead.
 
 =head1 AUTHOR AND COPYRIGHT
 
-Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and
+Copyright (c) 1997-2006 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/pod/perlfaq9.pod b/pod/perlfaq9.pod
index 2649372cc6..27aa8d4f25 100644
--- a/pod/perlfaq9.pod
+++ b/pod/perlfaq9.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq9 - Networking ($Revision: 1.26 $, $Date: 2005/11/21 17:43:13 $)
+perlfaq9 - Networking ($Revision: 1.28 $, $Date: 2005/12/31 00:54:37 $)
 
 =head1 DESCRIPTION
 
@@ -606,14 +606,14 @@ in perl5.7.3, can get you the fully qualified domain name (FQDN), the host
 name, or the domain name.
 
 	use Net::Domain qw(hostname hostfqdn hostdomain);
-	
+
 	my $host = hostfqdn();
 
 The C<Sys::Hostname> module, included in the standard distribution since
 perl5.6, can also get the hostname.
 
 	use Sys::Hostname;
-	
+
 	$host = hostname();
 
 To get the IP address, you can use the C<gethostbyname> built-in function
@@ -622,8 +622,8 @@ form (a.b.c.d) that most people expect, use the C<inet_ntoa> function
 from the <Socket> module, which also comes with perl.
 
     use Socket;
-    
-    my $address = inet_ntoa( 
+
+    my $address = inet_ntoa(
     	scalar gethostbyname( $host || 'localhost' )
     	);
 
@@ -649,7 +649,7 @@ http://search.cpan.org/search?query=RPC&mode=all ).
 
 =head1 AUTHOR AND COPYRIGHT
 
-Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and
+Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and
 other authors as noted. All rights reserved.
 
 This documentation is free; you can redistribute it and/or modify it