FAQ sync

p4raw-id: //depot/perl@29282

7 files changed, 122 insertions, 95 deletions

diff --git a/pod/perlfaq.pod b/pod/perlfaq.pod
index c75da2e27b..037268e4e9 100644
--- a/pod/perlfaq.pod
+++ b/pod/perlfaq.pod
@@ -127,7 +127,7 @@ What are perl4, perl5, or perl6?
 
 =item *
 
-What is Ponie?
+What was Ponie?
 
 =item *
 
diff --git a/pod/perlfaq1.pod b/pod/perlfaq1.pod
index 72a523287f..71fd84fc79 100644
--- a/pod/perlfaq1.pod
+++ b/pod/perlfaq1.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq1 - General Questions About Perl ($Revision: 7822 $)
+perlfaq1 - General Questions About Perl ($Revision: 7997 $)
 
 =head1 DESCRIPTION
 
@@ -150,20 +150,20 @@ http://dev.perl.org/perl6/ .
 
 See L<perlhist> for a history of Perl revisions.
 
-=head2 What is Ponie?
+=head2 What was Ponie?
 
 (contributed by brian d foy)
 
 Ponie stands for "Perl On the New Internal Engine", started by Arthur
 Bergman from Fotango in 2003, and subsequently run as a project of The
-Perl Foundation. Instead of using the current Perl internals, Ponie
-creates a new one that provides a translation path from Perl 5 to Perl 6
-(or anything else that targets Parrot, actually). You can also just keep
-using Perl 5 with Parrot, the virtual machine which will compile and run
-Perl 6 bytecode.
+Perl Foundation. It was abandoned in 2006
+U<http://www.nntp.perl.org/group/perl.ponie.dev/487> .
 
-You can get more information at http://www.poniecode.org/ and
-http://www.parrotcode.org .
+Instead of using the current Perl internals, Ponie aimed to create a
+new one that would provide a translation path from Perl 5 to Perl 6
+(or anything else that targets Parrot, actually). You would have been
+able  to just keep using Perl 5 with Parrot, the virtual machine which
+will compile and run Perl 6 bytecode.
 
 =head2 What is perl6?
 
@@ -390,9 +390,9 @@ You might find these links useful:
 
 =head1 REVISION
 
-Revision: $Revision: 7822 $
+Revision: $Revision: 7997 $
 
-Date: $Date: 2006-09-11 14:22:59 +0200 (lun, 11 sep 2006) $
+Date: $Date: 2006-11-01 09:29:17 +0100 (mer, 01 nov 2006) $
 
 See L<perlfaq> for source control details and availability.
 
diff --git a/pod/perlfaq2.pod b/pod/perlfaq2.pod
index 31c1b2c17a..2123c9e34f 100644
--- a/pod/perlfaq2.pod
+++ b/pod/perlfaq2.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq2 - Obtaining and Learning about Perl ($Revision: 7861 $)
+perlfaq2 - Obtaining and Learning about Perl ($Revision: 7996 $)
 
 =head1 DESCRIPTION
 
@@ -32,6 +32,15 @@ might be based upon a less current source release of perl).
 
 =head2 How can I get a binary version of perl?
 
+For Windows, ActiveState provides a pre-built Perl for free:
+
+	http://www.activestate.com/
+
+Sunfreeware.com provides binaries for many utilities, including
+Perl, for Solaris on both Intel and SPARC hardware:
+
+	http://www.sunfreeware.com/
+
 If you don't have a C compiler because your vendor for whatever
 reasons did not include one with your system, the best thing to do is
 grab a binary version of gcc from the net and use that to compile perl
@@ -40,13 +49,13 @@ get free compilers for, not for Unix systems.
 
 Some URLs that might help you are:
 
-    http://www.cpan.org/ports/
-    http://www.perl.com/pub/language/info/software.html
+	http://www.cpan.org/ports/
+	http://www.perl.com/pub/language/info/software.html
 
-Someone looking for a perl for Win16 might look to Laszlo Molnar's djgpp
-port in http://www.cpan.org/ports/#msdos , which comes with clear
-installation instructions.  A simple installation guide for MS-DOS using
-Ilya Zakharevich's OS/2 port is available at
+Someone looking for a perl for Win16 might look to Laszlo Molnar's
+djgpp port in http://www.cpan.org/ports/#msdos , which comes with
+clear installation instructions.  A simple installation guide for
+MS-DOS using Ilya Zakharevich's OS/2 port is available at
 http://www.cs.ruu.nl/%7Epiet/perl5dos.html
 and similarly for Windows 3.1 at http://www.cs.ruu.nl/%7Epiet/perlwin3.html .
 
@@ -501,9 +510,9 @@ the I<What is CPAN?> question earlier in this document.
 
 =head1 REVISION
 
-Revision: $Revision: 7861 $
+Revision: $Revision: 7996 $
 
-Date: $Date: 2006-09-29 22:19:18 +0200 (ven, 29 sep 2006) $
+Date: $Date: 2006-11-01 09:24:38 +0100 (mer, 01 nov 2006) $
 
 See L<perlfaq> for source control details and availability.
 
diff --git a/pod/perlfaq4.pod b/pod/perlfaq4.pod
index 38a0e91328..b4945d3099 100644
--- a/pod/perlfaq4.pod
+++ b/pod/perlfaq4.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq4 - Data Manipulation ($Revision: 7954 $)
+perlfaq4 - Data Manipulation ($Revision: 7996 $)
 
 =head1 DESCRIPTION
 
@@ -1006,9 +1006,13 @@ C<Text::Metaphone>, and C<Text::DoubleMetaphone> modules.
 
 (contributed by brian d foy)
 
-For example, I'll use a string that has two Perl scalar variables
-in it. In this example, I want to expand C<$foo> and C<$bar> to
-their variable's values.
+If you can avoid it, don't, or if you can use a templating system,
+such as C<Text::Template> or C<Template> Toolkit, do that instead.
+
+However, for the one-off simple case where I don't want to pull out a
+full templating system, I'll use a string that has two Perl scalar
+variables in it. In this example, I want to expand C<$foo> and C<$bar>
+to their variable's values.
 
 	my $foo = 'Fred';
 	my $bar = 'Barney';
@@ -1021,7 +1025,7 @@ it with its value. C<$foo>, then, turns into 'Fred', and that's finally
 what's left in the string.
 
 	$string =~ s/(\$\w+)/$1/eeg; # 'Say hello to Fred and Barney'
-	
+
 The C</e> will also silently ignore violations of strict, replacing
 undefined variable names with the empty string.
 
@@ -1035,14 +1039,14 @@ with a marker, in this case C<???> to signal that I missed something:
 	my %Replacements = (
 		foo  => 'Fred',
 		);
-		
+
 	# $string =~ s/\$(\w+)/$Replacements{$1}/g;
 	$string =~ s/\$(\w+)/
 		exists $Replacements{$1} ? $Replacements{$1} : '???'
 		/eg;
-		
+
 	print $string;
-	
+
 =head2 What's wrong with always quoting "$vars"?
 
 The problem is that those double-quotes force
@@ -2215,9 +2219,9 @@ the C<PDL> module from CPAN instead--it makes number-crunching easy.
 
 =head1 REVISION
 
-Revision: $Revision: 7954 $
+Revision: $Revision: 7996 $
 
-Date: $Date: 2006-10-16 22:07:58 +0200 (lun, 16 oct 2006) $
+Date: $Date: 2006-11-01 09:24:38 +0100 (mer, 01 nov 2006) $
 
 See L<perlfaq> for source control details and availability.
 
diff --git a/pod/perlfaq5.pod b/pod/perlfaq5.pod
index d171522e1a..d9ad4c3ee7 100644
--- a/pod/perlfaq5.pod
+++ b/pod/perlfaq5.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq5 - Files and Formats ($Revision: 7875 $)
+perlfaq5 - Files and Formats ($Revision: 8075 $)
 
 =head1 DESCRIPTION
 
@@ -801,7 +801,7 @@ then that is what you should do.
 
 If you know you are only going to use a system that does correctly
 implement appending (i.e. not Win32) then you can omit the seek() from
-the above code.
+the code in the previous answer.
 
 If you know you are only writing code to run on an OS and filesystem that
 does implement append mode correctly (a local filesystem on a modern
@@ -1265,9 +1265,9 @@ If your array contains lines, just print them:
 
 =head1 REVISION
 
-Revision: $Revision: 7875 $
+Revision: $Revision: 8075 $
 
-Date: $Date: 2006-10-04 22:39:26 +0200 (mer, 04 oct 2006) $
+Date: $Date: 2006-11-15 02:26:49 +0100 (mer, 15 nov 2006) $
 
 See L<perlfaq> for source control details and availability.
 
diff --git a/pod/perlfaq7.pod b/pod/perlfaq7.pod
index 65ff7a70c5..0d055f57f2 100644
--- a/pod/perlfaq7.pod
+++ b/pod/perlfaq7.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq7 - General Perl Language Issues ($Revision: 7875 $)
+perlfaq7 - General Perl Language Issues ($Revision: 7998 $)
 
 =head1 DESCRIPTION
 
@@ -213,20 +213,21 @@ See also L<perlsec/"Laundering and Detecting Tainted Data">.
 Closures are documented in L<perlref>.
 
 I<Closure> is a computer science term with a precise but
-hard-to-explain meaning. Closures are implemented in Perl as anonymous
-subroutines with lasting references to lexical variables outside their
-own scopes.  These lexicals magically refer to the variables that were
-around when the subroutine was defined (deep binding).
-
-Closures make sense in any programming language where you can have the
-return value of a function be itself a function, as you can in Perl.
-Note that some languages provide anonymous functions but are not
-capable of providing proper closures: the Python language, for
+hard-to-explain meaning. Usually, closures are implemented in Perl as
+anonymous subroutines with lasting references to lexical variables
+outside their own scopes. These lexicals magically refer to the
+variables that were around when the subroutine was defined (deep 
+binding).
+
+Closures are most often used in programming languages where you can
+have the return value of a function be itself a function, as you can
+in Perl. Note that some languages provide anonymous functions but are
+not capable of providing proper closures: the Python language, for
 example.  For more information on closures, check out any textbook on
 functional programming.  Scheme is a language that not only supports
 but encourages closures.
 
-Here's a classic function-generating function:
+Here's a classic non-closure function-generating function:
 
     sub add_function_generator {
       return sub { shift() + shift() };
@@ -235,10 +236,10 @@ Here's a classic function-generating function:
     $add_sub = add_function_generator();
     $sum = $add_sub->(4,5);                # $sum is 9 now.
 
-The closure works as a I<function template> with some customization
-slots left out to be filled later.  The anonymous subroutine returned
-by add_function_generator() isn't technically a closure because it
-refers to no lexicals outside its own scope.
+The anonymous subroutine returned by add_function_generator() isn't
+technically a closure because it refers to no lexicals outside its own
+scope.  Using a closure gives you a I<function template> with some
+customization slots left out to be filled later.
 
 Contrast this with the following make_adder() function, in which the
 returned anonymous function contains a reference to a lexical variable
@@ -269,6 +270,21 @@ C<< '$line = <STDIN>' >>, there would have been no way for the
 hypothetical timeout() function to access the lexical variable
 $line back in its caller's scope.
 
+Another use for a closure is to make a variable I<private> to a
+named subroutine, e.g. a counter that gets initialized at creation
+time of the sub and can only be modified from within the sub.
+This is sometimes used with a BEGIN block in package files to make
+sure a variable doesn't get meddled with during the lifetime of the
+package:
+
+    BEGIN {
+        my $id = 0;
+        sub next_id { ++$id }
+    }
+
+This is discussed in more detail in L<perlsub>, see the entry on
+I<Persistent Private Variables>.
+
 =head2 What is variable suicide and how can I prevent it?
 
 This problem was fixed in perl 5.004_05, so preventing it means upgrading
@@ -962,9 +978,9 @@ where you expect it so you need to adjust your shebang line.
 
 =head1 REVISION
 
-Revision: $Revision: 7875 $
+Revision: $Revision: 7998 $
 
-Date: $Date: 2006-10-04 22:39:26 +0200 (mer, 04 oct 2006) $
+Date: $Date: 2006-11-01 09:56:34 +0100 (mer, 01 nov 2006) $
 
 See L<perlfaq> for source control details and availability.
 
diff --git a/pod/perlfaq9.pod b/pod/perlfaq9.pod
index 0a2ef460b6..54d6674b4e 100644
--- a/pod/perlfaq9.pod
+++ b/pod/perlfaq9.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq9 - Networking ($Revision: 7875 $)
+perlfaq9 - Networking ($Revision: 8076 $)
 
 =head1 DESCRIPTION
 
@@ -407,54 +407,52 @@ of the task.  It's much easier and less hassle to use CGI.pm.
 
 =head2 How do I check a valid mail address?
 
-You can't, at least, not in real time.  Bummer, eh?
+(partly contributed by Aaron Sherman)
 
-Without sending mail to the address and seeing whether there's a human
-on the other end to answer you, you cannot determine whether a mail
-address is valid.  Even if you apply the mail header standard, you
-can have problems, because there are deliverable addresses that aren't
-RFC-822 (the mail header standard) compliant, and addresses that aren't
-deliverable which are compliant.
-
-You can use the Email::Valid or RFC::RFC822::Address which check
-the format of the address, although they cannot actually tell you
-if it is a deliverable address (i.e. that mail to the address
-will not bounce).  Modules like Mail::CheckUser and Mail::EXPN
-try to interact with the domain name system or particular
-mail servers to learn even more, but their methods do not
-work everywhere--especially for security conscious administrators.
-
-Many are tempted to try to eliminate many frequently-invalid
-mail addresses with a simple regex, such as
-C</^[\w.-]+\@(?:[\w-]+\.)+\w+$/>.  It's a very bad idea.  However,
-this also throws out many valid ones, and says nothing about
-potential deliverability, so it is not suggested.  Instead, see
-http://www.cpan.org/authors/Tom_Christiansen/scripts/ckaddr.gz ,
-which actually checks against the full RFC spec (except for nested
-comments), looks for addresses you may not wish to accept mail to
-(say, Bill Clinton or your postmaster), and then makes sure that the
-hostname given can be looked up in the DNS MX records.  It's not fast,
-but it works for what it tries to do.
+This isn't as simple a question as it sounds.  There are two parts:
 
-Our best advice for verifying a person's mail address is to have them
-enter their address twice, just as you normally do to change a password.
-This usually weeds out typos.  If both versions match, send
-mail to that address with a personal message that looks somewhat like:
+a) How do I verify that an email address is correctly formatted?
 
-    Dear someuser@host.com,
+b) How do I verify that an email address targets a valid recipient?
 
-    Please confirm the mail address you gave us Wed May  6 09:38:41
-    MDT 1998 by replying to this message.  Include the string
-    "Rumpelstiltskin" in that reply, but spelled in reverse; that is,
-    start with "Nik...".  Once this is done, your confirmed address will
-    be entered into our records.
+Without sending mail to the address and seeing whether there's a human
+on the other end to answer you, you cannot fully answer part I<b>, but
+either the C<Email::Valid> or the C<RFC::RFC822::Address> module will do
+both part I<a> and part I<b> as far as you can in real-time.
+
+If you want to just check part I<a> to see that the address is valid
+according to the mail header standard with a simple regular expression,
+you can have problems, because there are deliverable addresses that
+aren't RFC-2822 (the latest mail header standard) compliant, and
+addresses that aren't deliverable which, are compliant.  However,  the
+following will match valid RFC-2822 addresses that do not have comments,
+folding whitespace, or any other obsolete or non-essential elements.
+This I<just> matches the address itself:
+
+    my $atom       = qr{[a-zA-Z0-9_!#\$\%&'*+/=?\^`{}~|\-]+};
+    my $dot_atom   = qr{$atom(?:\.$atom)*};
+    my $quoted     = qr{"(?:\\[^\r\n]|[^\\"])*"};
+    my $local      = qr{(?:$dot_atom|$quoted)};
+    my $domain_lit = qr{\[(?:\\\S|[\x21-\x5a\x5e-\x7e])*\]};
+    my $domain     = qr{(?:$dot_atom|$domain_lit)};
+    my $addr_spec  = qr{$local\@$domain};
+
+Just match an address against C</^${addr_spec}$/> to see if it follows
+the RFC2822 specification.  However, because it is impossible to be
+sure that such a correctly formed address is actually the correct way
+to reach a particular person or even has a mailbox associated with it,
+you must be very careful about how you use this.
 
-If you get the message back and they've followed your directions,
-you can be reasonably assured that it's real.
+Our best advice for verifying a person's mail address is to have them
+enter their address twice, just as you normally do to change a
+password. This usually weeds out typos. If both versions match, send
+mail to that address with a personal message. If you get the message
+back and they've followed your directions, you can be reasonably
+assured that it's real.
 
 A related strategy that's less open to forgery is to give them a PIN
 (personal ID number).  Record the address and PIN (best that it be a
-random one) for later processing.  In the mail you send, ask them to
+random one) for later processing. In the mail you send, ask them to
 include the PIN in their reply.  But if it bounces, or the message is
 included via a "vacation" script, it'll be there anyway.  So it's
 best to ask them to mail back a slight alteration of the PIN, such as
@@ -667,9 +665,9 @@ http://search.cpan.org/search?query=RPC&mode=all ).
 
 =head1 REVISION
 
-Revision: $Revision: 7875 $
+Revision: $Revision: 8076 $
 
-Date: $Date: 2006-10-04 22:39:26 +0200 (mer, 04 oct 2006) $
+Date: $Date: 2006-11-15 14:53:23 +0100 (mer, 15 nov 2006) $
 
 See L<perlfaq> for source control details and availability.