Integrate:

[ 26625]
Subject: Re: [perl #38034] A combination eval, DESTROY method and $@ - dangerous - bug
From: Mike Guy <mjtg@cam.ac.uk>
Date: Tue, 03 Jan 2006 19:18:41 +0000 
Message-Id: <E1Etrg9-0005XE-LZ@libra.cus.cam.ac.uk> 

[ 26669]
Improve description of the -s switch.
I found the "This means you can have switches
with two leading dashes." sentence introduced by
change 7144 really confusing.  The note after
the example should make it clear enough that double
dash switches can be used for those that insist.

[ 26797]
Typo fix.

[ 26801]
FAQ sync.

[ 26802]
Subject: [perl #38205] misleading typo in perlfaq8
From: erik@cs.uni-jena.de (via RT) <perlbug-followup@perl.org>
Date: Wed, 11 Jan 2006 14:56:28 -0800
Message-ID: <rt-3.0.11-38205-127890.10.340635502974@perl.org>

[ 26814]
Add a link to the Opcode doc in Safe.
(see RT CPAN ticket #8579)

[ 26816]
Better wording for change 26796. Plus, make podchecker happy.

[ 26819]
Fix internal links in POD.
p4raw-link: @26819 on //depot/perl: 0f414b9566e174d41eb2dcd375172be5f19a5e0d
p4raw-link: @26816 on //depot/perl: a7845df8f6bfd9f3b7e686165ebf73c1549cb163
p4raw-link: @26814 on //depot/perl: 86f9b3f5301683c929b08a4c5aeebe5c4bab44d0
p4raw-link: @26802 on //depot/perl: 764289d88134dd8424d60ca15744b687b335cc99
p4raw-link: @26801 on //depot/perl: fcd1fd077902cb9c74aa07dca8a5c26406bc995d
p4raw-link: @26797 on //depot/perl: af7a0647e92ea0b5030ae86067c3fa353ecdbe3f
p4raw-link: @26669 on //depot/perl: 74ac850a5ee417afa60a477ea52af7a8f46a7e5a
p4raw-link: @26625 on //depot/perl: f4551fcd8535f92b446c0bbb84dfd670a1f3eece

p4raw-id: //depot/maint-5.8/perl@26822
p4raw-integrated: from //depot/perl@26821 'copy in' ext/Opcode/Safe.pm
	(@23025..) lib/utf8.pm (@24399..) pod/perlobj.pod (@26218..)
	pod/perlfaq.pod pod/perlfaq2.pod pod/perlfaq8.pod (@26601..)
	lib/PerlIO.pm (@26796..) 'merge in' pod/perlrun.pod (@26571..)
	pod/perlvar.pod (@26750..)

6 files changed, 70 insertions, 76 deletions

diff --git a/pod/perlfaq.pod b/pod/perlfaq.pod
index bb1935e3dc..f892238c02 100644
--- a/pod/perlfaq.pod
+++ b/pod/perlfaq.pod
@@ -1,72 +1,79 @@
 =head1 NAME
 
-perlfaq - frequently asked questions about Perl ($Date: 2005/12/30 15:04:07 $)
+perlfaq - frequently asked questions about Perl
 
 =head1 DESCRIPTION
 
-The perlfaq is divided into several documents based on topics.  A table
-of contents is at the end of this document.
+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
 
-Extracts of the perlfaq are posted regularly to
-comp.lang.perl.misc.  It is available on many web sites:
-http://www.perldoc.com/ and http://faq.perl.org/
+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 let's you read the L<perlfaq>:
 
-=head2 How to contribute to the perlfaq
+	$ perldoc perlfaq
 
-You may mail corrections, additions, and suggestions to
-perlfaq-workers@perl.org .  This alias should not be used to
-I<ask> FAQs.  It's for fixing the current FAQ. Send
-questions to the comp.lang.perl.misc newsgroup.  You can
-view the source tree at http://cvs.perl.org/cvsweb/perlfaq/
-(which is outside of the main Perl source tree).  The CVS
-repository notes all changes to the FAQ.
+Besides your local system, you can find the perlfaq on the web, including
+at http://perldoc.perl.org/ .
 
-=head2 What will happen if you mail your Perl programming problems to the authors
+The perlfaq is an evolving document and you can read the latest version
+at http://faq.perl.org/ . The perlfaq-workers periodically post extracts
+of the latest perlfaq to comp.lang.perl.misc.
 
-Your questions will probably go unread, unless they're
-suggestions of new questions to add to the FAQ, in which
-case they should have gone to the perlfaq-workers@perl.org
-instead.
+You can view the source tree at
+http://cvs.perl.org/viewcvs/cvs-public/perlfaq/ (which is outside of the
+main Perl source tree).  The CVS repository notes all changes to the FAQ
+and holds the latest version of the working documents and may vary
+significantly from the version distributed with the latest version of
+Perl. Check the repository before sending your corrections.
 
-You should have read section 2 of this faq.  There you would
-have learned that comp.lang.perl.misc is the appropriate
-place to go for free advice.  If your question is really
-important and you require a prompt and correct answer, you
-should hire a consultant.
+=head2 How to contribute to the perlfaq
 
-=head1 Credits
+You can mail corrections, additions, and suggestions to 
+C<< <perlfaq-workers AT perl DOT org> >>. The perlfaq volunteers use this
+address to coordinate their efforts and track the perlfaq development.
+They appreciate your contributions to the FAQ but do not have time to
+provide individual help, so don't use this address to ask FAQs.
 
-The original perlfaq was written by Tom Christiansen, then expanded
-by collaboration between Tom and Nathan Torkington.  The current
-document is maintained by the perlfaq-workers (perlfaq-workers@perl.org).
-Several people have contributed answers, corrections, and comments.
+The perlfaq server posts extracts of the perlfaq to that newsgroup every
+6 hours (or so), and the community of volunteers reviews and updates the
+answers. If you'd like to help review and update the answers, check out
+comp.lang.perl.misc.
 
-=head1 Author and Copyright Information
+=head2 What will happen if you mail your Perl programming problems to the authors?
 
-Copyright (c) 1997-2005 Tom Christiansen, Nathan Torkington, and
-other contributors noted in the answers.
+The perlfaq-workers like to keep all traffic on the perlfaq-workers list
+so that everyone can see the work being done (and the work that needs to
+be done). The mailing list serves as an official record. If you email the
+authors or maintainers directly, you'll probably get a reply asking you
+to post to the mailing list. If you don't get a reply, it probably means
+that the person never saw the message or didn't have time to deal with
+it. Posting to the list allows the volunteers with time to deal with it
+when others are busy.
 
-All rights reserved.
+If you have a question that isn't in the FAQ and you would like help with
+it, try the resources in L<perlfaq2>.
 
-=head2 Bundled Distributions
+=head1 CREDITS
 
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
+Tom Christiansen wrote the original perlfaq then expanded it with the
+help of Nat Torkington.  The perlfaq-workers maintain current document
+and the dezinens of comp.lang.perl.misc regularly review and update the
+FAQ. Several people have contributed answers, corrections, and comments,
+and the perlfaq notes those contributions wherever appropriate.
 
-Irrespective of its distribution, all code examples in these files
-are hereby placed into the public domain.  You are permitted and
-encouraged to use this code in your own programs for fun
-or for profit as you see fit.  A simple comment in the code giving
-credit would be courteous but is not required.
+=head1 AUTHOR AND COPYRIGHT
 
-=head2 Disclaimer
+Tom Christainsen 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 information is offered in good faith and in the hope that it may
-be of use, but is not guaranteed to be correct, up to date, or suitable
-for any particular purpose whatsoever.  The authors accept no liability
-in respect of this information or its use.
+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).
 
 =head1 Table of Contents
 
@@ -92,13 +99,10 @@ in respect of this information or its use.
 
 =item perlfaq9 - Networking
 
-
 =back
 
-
 =head1 The Questions
 
-
 =head2 L<perlfaq1>: General Questions About Perl
 
 Very general, high-level questions about Perl.
@@ -224,11 +228,7 @@ Perl Books
 
 =item *
 
-Perl in Magazines
-
-=item *
-
-Perl on the Net: FTP and WWW Access
+Which magazines have Perl content?
 
 =item *
 
@@ -236,7 +236,7 @@ What mailing lists are there for Perl?
 
 =item *
 
-Archives of comp.lang.perl.misc
+Where are the archives for comp.lang.perl.misc?
 
 =item *
 
diff --git a/pod/perlfaq2.pod b/pod/perlfaq2.pod
index ac34be2c01..ed4199615a 100644
--- a/pod/perlfaq2.pod
+++ b/pod/perlfaq2.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.38 $, $Date: 2005/12/31 00:54:37 $)
+perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.39 $, $Date: 2006/01/08 14:27:07 $)
 
 =head1 DESCRIPTION
 
@@ -404,7 +404,7 @@ Recommended books on (or mostly on) Perl follow.
 
 =back
 
-=head2 Perl in Magazines
+=head2 Which magazines have Perl content?
 
 The first (and for a long time, only) periodical devoted to All Things Perl,
 I<The Perl Journal> contains tutorials, demonstrations, case studies,
@@ -427,16 +427,6 @@ http://www.stonehenge.com/merlyn/WebTechniques/ ,
 http://www.stonehenge.com/merlyn/UnixReview/ , and
 http://www.stonehenge.com/merlyn/LinuxMag/ .
 
-=head2 Perl on the Net: FTP and WWW Access
-
-To get the best performance, pick a site from the list at
-http://www.cpan.org/SITES.html . From there you can find the quickest
-site for you.
-
-You may also use xx.cpan.org where "xx" is the 2-letter country code
-for your domain; e.g. Australia would use au.cpan.org. [Note: This
-only applies to countries that host at least one mirror.]
-
 =head2 What mailing lists are there for Perl?
 
 Most of the major modules (Tk, CGI, libwww-perl) have their own
@@ -447,7 +437,7 @@ A comprehensive list of Perl related mailing lists can be found at:
 
 	http://lists.perl.org/
 
-=head2 Archives of comp.lang.perl.misc
+=head2 Where are the archives for comp.lang.perl.misc?
 
 The Google search engine now carries archived and searchable newsgroup
 content.
diff --git a/pod/perlfaq8.pod b/pod/perlfaq8.pod
index 55c3cbf899..cc65a1fe8f 100644
--- a/pod/perlfaq8.pod
+++ b/pod/perlfaq8.pod
@@ -666,8 +666,8 @@ files:
     use IPC::Open3;
     use Symbol qw(gensym);
     use IO::File;
-    local *CATCHOUT = IO::File->new_tempfile;
-    local *CATCHERR = IO::File->new_tempfile;
+    local *CATCHOUT = IO::File->new_tmpfile;
+    local *CATCHERR = IO::File->new_tmpfile;
     my $pid = open3(gensym, ">&CATCHOUT", ">&CATCHERR", "cmd");
     waitpid($pid, 0);
     seek $_, 0, 0 for \*CATCHOUT, \*CATCHERR;
@@ -680,7 +680,7 @@ should work just as well, without deadlocking:
     use IPC::Open3;
     use Symbol qw(gensym);
     use IO::File;
-    local *CATCHERR = IO::File->new_tempfile;
+    local *CATCHERR = IO::File->new_tmpfile;
     my $pid = open3(gensym, \*CATCHOUT, ">&CATCHERR", "cmd");
     while( <CATCHOUT> ) {}
     waitpid($pid, 0);
diff --git a/pod/perlobj.pod b/pod/perlobj.pod
index bcf56a7a1c..6cfa20ce8e 100644
--- a/pod/perlobj.pod
+++ b/pod/perlobj.pod
@@ -456,6 +456,11 @@ manipulating C<$_[0]> within the destructor.  The object itself (i.e.
 the thingy the reference points to, namely C<${$_[0]}>, C<@{$_[0]}>, 
 C<%{$_[0]}> etc.) is not similarly constrained.
 
+Since DESTROY methods can be called at unpredictable times, it is
+important that you localise any global variables that the method may
+update.  In particular, localise C<$@> if you use C<eval {}> and
+localise C<$?> if you use C<system> or backticks.
+
 If you arrange to re-bless the reference before the destructor returns,
 perl will again call the DESTROY method for the re-blessed object after
 the current one returns.  This can be used for clean delegation of
diff --git a/pod/perlrun.pod b/pod/perlrun.pod
index 1299ab4f63..7b9dacaed2 100644
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -748,8 +748,7 @@ X<-s>
 
 enables rudimentary switch parsing for switches on the command
 line after the program name but before any filename arguments (or before
-an argument of B<-->).  This means you can have switches with two leading
-dashes (B<--help>).  Any switch found there is removed from @ARGV and sets the
+an argument of B<-->).  Any switch found there is removed from @ARGV and sets the
 corresponding variable in the Perl program.  The following program
 prints "1" if the program is invoked with a B<-xyz> switch, and "abc"
 if it is invoked with B<-xyz=abc>.
@@ -757,7 +756,7 @@ if it is invoked with B<-xyz=abc>.
     #!/usr/bin/perl -s
     if ($xyz) { print "$xyz\n" }
 
-Do note that B<--help> creates the variable ${-help}, which is not compliant
+Do note that a switch like B<--help> creates the variable ${-help}, which is not compliant
 with C<strict refs>.  Also, when using this option on a script with
 warnings enabled you may get a lot of spurious "used only once" warnings.
 
diff --git a/pod/perlvar.pod b/pod/perlvar.pod
index 1c8cfdc35b..acb35a94b7 100644
--- a/pod/perlvar.pod
+++ b/pod/perlvar.pod
@@ -897,8 +897,8 @@ directive, and cannot influence the behavior of any other file.
 Its use is highly discouraged.
 
 Note that, unlike other compile-time directives (such as L<strict>),
-assignment to $[ can be seen from outer lexical scopes in the same file.
-However, you can use local() on it to strictly bound its value to a
+assignment to C<$[> can be seen from outer lexical scopes in the same file.
+However, you can use local() on it to strictly bind its value to a
 lexical block.
 
 =item $]