FAQ sync. (Ignoring the few URL differences for now.)

p4raw-id: //depot/perl@15813

8 files changed, 52 insertions, 59 deletions

diff --git a/pod/perlfaq1.pod b/pod/perlfaq1.pod
index dcaed0648f..5ca94c99f0 100644
--- a/pod/perlfaq1.pod
+++ b/pod/perlfaq1.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq1 - General Questions About Perl ($Revision: 1.7 $, $Date: 2002/02/21 14:49:15 $)
+perlfaq1 - General Questions About Perl ($Revision: 1.8 $, $Date: 2002/04/07 18:46:13 $)
 
 =head1 DESCRIPTION
 
@@ -37,7 +37,7 @@ are a rag-tag band of highly altruistic individuals committed to
 producing better software for free than you could hope to purchase for
 money.  You may snoop on pending developments via the archives at
 http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/
-and http://archive.develooper.com/perl5-porters@perl.org/ 
+and http://archive.develooper.com/perl5-porters@perl.org/
 or the news gateway nntp://nntp.perl.org/perl.perl5.porters or
 its web interface at http://nntp.perl.org/group/perl.perl5.porters ,
 or read the faq at http://perlhacker.org/p5p-faq ,
diff --git a/pod/perlfaq2.pod b/pod/perlfaq2.pod
index 4555714df4..04e7351aea 100644
--- a/pod/perlfaq2.pod
+++ b/pod/perlfaq2.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.9 $, $Date: 2002/03/09 21:01:13 $)
+perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.11 $, $Date: 2002/04/08 15:39:59 $)
 
 =head1 DESCRIPTION
 
@@ -185,8 +185,8 @@ following groups:
 
 There is also a Usenet gateway to Perl mailing lists sponsored by perl.org at 
 nntp://nntp.perl.org, or a web interface to the same lists at
-http://nntp.perl.org/group/ .  Other groups are listed at 
-http://lists.perl.org/
+http://nntp.perl.org/group/.  Other groups are listed at 
+http://lists.perl.org/ .
 
 =head2 Where should I post source code?
 
@@ -197,8 +197,8 @@ including setting the Followup-To header line to NOT include alt.sources;
 see their FAQ ( http://www.faqs.org/faqs/alt-sources-intro/ ) for details.
 
 If you're just looking for software, first use Google
-( http://www.google.com/ ), Google's usenet search interface
-( http://groups.google.com/ ),  and CPAN Search ( http://search.cpan.org/ ).
+( http://www.google.com ), Google's usenet search interface
+( http://groups.google.com ),  and CPAN Search ( http://search.cpan.org ).  
 This is faster and more productive than just posting a request.
 
 =head2 Perl Books
@@ -375,7 +375,7 @@ development, databases, Win32 Perl, graphical programming, regular
 expressions, and networking, and sponsors the Obfuscated Perl Contest
 and the Perl Poetry Contests.  As of mid-2001, the dead tree version
 of TPJ will be published as a quarterly supplement of SysAdmin
-magazine ( http://www.sysadmin.com/ ) For more details on TPJ,
+magazine ( http://www.sysadminmag.com/ ) For more details on TPJ,
 see http://www.tpj.com/
 
 Beyond this, magazines that frequently carry quality articles on
@@ -394,7 +394,7 @@ http://www.stonehenge.com/merlyn/LinuxMag/ .
 
 To get the best performance, pick a site from
 the list below and use it to grab the complete list of mirror sites
-which is at /CPAN/MIRRORED.BY or at http://mirror.cpan.org/
+which is at /CPAN/MIRRORED.BY or at http://mirror.cpan.org/ .
 From there you can find the quickest site for you.  Remember, the
 following list is I<not> the complete list of CPAN mirrors
 (the complete list contains 165 sites as of January 2001):
@@ -407,7 +407,6 @@ following list is I<not> the complete list of CPAN mirrors
   ftp://ftp.uvsq.fr/pub/perl/CPAN/
   ftp://ftp.funet.fi/pub/languages/perl/CPAN/
   ftp://ftp.dti.ad.jp/pub/lang/CPAN/
-  ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
   ftp://cpan.if.usp.br/pub/mirror/CPAN/
 
 One may also use xx.cpan.org where "xx" is the 2-letter country code
diff --git a/pod/perlfaq3.pod b/pod/perlfaq3.pod
index 2ac18e7004..9a2908d731 100644
--- a/pod/perlfaq3.pod
+++ b/pod/perlfaq3.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq3 - Programming Tools ($Revision: 1.15 $, $Date: 2002/02/11 19:29:52 $)
+perlfaq3 - Programming Tools ($Revision: 1.17 $, $Date: 2002/04/08 15:39:59 $)
 
 =head1 DESCRIPTION
 
@@ -154,9 +154,9 @@ for indenting, ^D is for undenting, and ^O is for blockdenting--
 as it were.  A more complete example, with comments, can be found at
 http://www.cpan.org/authors/id/TOMC/scripts/toms.exrc.gz
 
-The a2ps http://www-inf.enst.fr/%7Edemaille/a2ps/black+white.ps.gz does
+The a2ps http://www-inf.enst.fr/%7Edemaille/a2ps/black+white.ps does
 lots of things related to generating nicely printed output of
-documents, as does enscript at http://people.ssh.fi/mtr/genscript/
+documents, as does enscript at http://people.ssh.fi/mtr/genscript/ .
 
 =head2 Is there a ctags for Perl?
 
@@ -191,7 +191,7 @@ Perl, a Visual Studio.NET plug-in is currently (early 2001) in beta
 
 =item The Object System
 
-( http://www.castlelink.co.uk/object_system/ ) is a Perl web
+(http://www.castlelink.co.uk/object_system/) is a Perl web
 applications development IDE, apparently for any platform
 that runs Perl.
 
@@ -240,11 +240,11 @@ information, although some allow you to save files as "Text
 Only". You can also download text editors designed
 specifically for programming, such as Textpad
 ( http://www.textpad.com/ ) and UltraEdit
-( http://www.ultraedit.com/ ), among others.
+( http://www.ultraedit.com ), among others.
 
 If you are using MacOS, the same concerns apply.  MacPerl
 (for Classic environments) comes with a simple editor.
-Popular external editors are BBEdit ( http://www.bbedit.com/ )
+Popular external editors are BBEdit ( http://www.bbedit.com )
 or Alpha ( http://alpha.olm.net/ ). MacOS X users can use Unix
 editors as well.
 
@@ -285,7 +285,8 @@ win32: http://www.cs.vu.nl/%7Etmgil/vi.html
 =back
 
 For vi lovers in general, Windows or elsewhere:
-http://www.thomer.com/thomer/vi/vi.html
+
+	http://www.thomer.com/thomer/vi/vi.html
 
 nvi ( http://www.bostic.com/vi/ , available from CPAN in src/misc/) is
 yet another vi clone, unfortunately not available for Windows, but in
@@ -384,7 +385,7 @@ For a complete version of Tom Christiansen's vi configuration file,
 see http://www.cpan.org/authors/Tom_Christiansen/scripts/toms.exrc.gz ,
 the standard benchmark file for vi emulators.  The file runs best with nvi,
 the current version of vi out of Berkeley, which incidentally can be built
-with an embedded Perl interpreter--see http://www.cpan.org/src/misc/
+with an embedded Perl interpreter--see http://www.cpan.org/src/misc .
 
 =head2 Where can I get perl-mode for emacs?
 
@@ -655,7 +656,7 @@ anything a module written in C can.  For more on mod_perl, see
 http://perl.apache.org/
 
 With the FCGI module (from CPAN) and the mod_fastcgi
-module ( available from http://www.fastcgi.com/ ) each of your Perl
+module (available from http://www.fastcgi.com/) each of your Perl
 programs becomes a permanent CGI daemon process.
 
 Both of these solutions can have far-reaching effects on your system
diff --git a/pod/perlfaq4.pod b/pod/perlfaq4.pod
index b530516431..bedc668c19 100644
--- a/pod/perlfaq4.pod
+++ b/pod/perlfaq4.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq4 - Data Manipulation ($Revision: 1.19 $, $Date: 2002/03/11 22:15:19 $)
+perlfaq4 - Data Manipulation ($Revision: 1.20 $, $Date: 2002/04/07 18:46:13 $)
 
 =head1 DESCRIPTION
 
@@ -1335,28 +1335,21 @@ lists, or you could just do something like this with an array:
 If you either have Perl 5.8.0 or later installed, or if you have
 Scalar-List-Utils 1.03 or later installed, you can say:
 
-        use List::Util 'shuffle';
+    use List::Util 'shuffle';
 
 	@shuffled = shuffle(@list);
 
-If not, you can use this:
+If not, you can use a Fisher-Yates shuffle.
 
-    # fisher_yates_shuffle
-    # generate a random permutation of an array in place
-    # As in shuffling a deck of cards
-    #
     sub fisher_yates_shuffle {
         my $deck = shift;  # $deck is a reference to an array
         my $i = @$deck;
-        while (--$i) {
+        while ($i--) {
             my $j = int rand ($i+1);
             @$deck[$i,$j] = @$deck[$j,$i];
         }
     }
 
-And here is an example of using it:
-
-    #
     # shuffle my mpeg collection
     #
     my @mpeg = <audio/*/*.mp3>;
diff --git a/pod/perlfaq5.pod b/pod/perlfaq5.pod
index 701a757558..4030824bf2 100644
--- a/pod/perlfaq5.pod
+++ b/pod/perlfaq5.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq5 - Files and Formats ($Revision: 1.12 $, $Date: 2002/03/11 22:25:25 $)
+perlfaq5 - Files and Formats ($Revision: 1.14 $, $Date: 2002/04/07 18:33:45 $)
 
 =head1 DESCRIPTION
 
@@ -763,21 +763,7 @@ more fun to use the standard DB_File module's $DB_RECNO bindings,
 which allow you to tie an array to a file so that accessing an element
 the array actually accesses the corresponding line in the file.
 
-On very rare occasion, you may have an algorithm that demands that
-the entire file be in memory at once as one scalar.  The simplest solution
-to that is
-
-    $var = `cat $file`;
-
-Being in scalar context, you get the whole thing.  In list context,
-you'd get a list of all the lines:
-
-    @lines = `cat $file`;
-
-This tiny but expedient solution is neat, clean, and portable to
-all systems on which decent tools have been installed.  For those
-who prefer not to use the toolbox, you can of course read the file
-manually, although this makes for more complicated code.
+You can read the entire filehandle contents into a scalar.
 
     {
 	local(*INPUT, $/);
@@ -790,6 +776,13 @@ close the file at block exit.  If the file is already open, just use this:
 
     $var = do { local $/; <INPUT> };
 
+For ordinary files you can also use the read function.
+
+	read( INPUT, $var, -s INPUT );
+
+The third argument tests the byte size of the data on the INPUT filehandle
+and reads that many bytes into the buffer $var.
+
 =head2 How can I read in a file by paragraphs?
 
 Use the C<$/> variable (see L<perlvar> for details).  You can either
diff --git a/pod/perlfaq6.pod b/pod/perlfaq6.pod
index dd76588ec0..6f9ee452ae 100644
--- a/pod/perlfaq6.pod
+++ b/pod/perlfaq6.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq6 - Regular Expressions ($Revision: 1.8 $, $Date: 2002/01/31 04:27:55 $)
+perlfaq6 - Regular Expressions ($Revision: 1.10 $, $Date: 2002/04/07 18:32:57 $)
 
 =head1 DESCRIPTION
 
@@ -634,10 +634,12 @@ L<perlfaq2>).
 
 =head2 What's wrong with using grep or map in a void context?
 
-Both grep and map build a return list, regardless of their context.
-This means you're making Perl go to the trouble of building up a
-return list that you then just ignore.  That's no way to treat a
-programming language, you insensitive scoundrel!
+The problem is that both grep and map build a return list,
+regardless of the context.  This means you're making Perl go
+to the trouble of building a list that you then just throw away.
+If the list is large, you waste both time and space.  If your
+intent is to iterate over the list then use a for loop for this
+purpose.
 
 =head2 How can I match strings with multibyte characters?
 
diff --git a/pod/perlfaq7.pod b/pod/perlfaq7.pod
index 96c5870d81..008f433124 100644
--- a/pod/perlfaq7.pod
+++ b/pod/perlfaq7.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq7 - General Perl Language Issues ($Revision: 1.7 $, $Date: 2002/01/31 04:27:55 $)
+perlfaq7 - General Perl Language Issues ($Revision: 1.8 $, $Date: 2002/03/26 15:48:32 $)
 
 =head1 DESCRIPTION
 
@@ -741,7 +741,8 @@ not necessarily the same as the one in which you were compiled):
 
 =head2 How can I comment out a large block of perl code?
 
-Use embedded POD to discard it:
+You can use embedded POD to discard it.  The =for directive
+lasts until the next paragraph (two consecutive newlines).
 
     # program is here
 
@@ -750,6 +751,9 @@ Use embedded POD to discard it:
 
     # program continues
 
+The =begin and =end directives can contain multiple
+paragraphs.
+
     =begin comment text
 
     all of this stuff
@@ -759,11 +763,12 @@ Use embedded POD to discard it:
 
     =end comment text
 
-    =cut
+The pod directives cannot go just anywhere.  You must put a
+pod directive where the parser is expecting a new statement,
+not just in the middle of an expression or some other
+arbitrary s grammar production.
 
-This can't go just anywhere.  You have to put a pod directive where
-the parser is expecting a new statement, not just in the middle
-of an expression or some other arbitrary yacc grammar production.
+See L<perlpod> for more details.
 
 =head2 How do I clear a package?
 
diff --git a/pod/perlfaq9.pod b/pod/perlfaq9.pod
index 947c769f8e..e643c33981 100644
--- a/pod/perlfaq9.pod
+++ b/pod/perlfaq9.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq9 - Networking ($Revision: 1.7 $, $Date: 2002/01/28 04:17:27 $)
+perlfaq9 - Networking ($Revision: 1.9 $, $Date: 2002/04/07 18:46:13 $)
 
 =head1 DESCRIPTION
 
@@ -253,7 +253,7 @@ Basically, the following substitutions do it:
 
     s/([^\w()'*~!.-])/sprintf '%%%02x', ord $1/eg;   # encode
 
-    s/%([A-Fa-f\d]{2})/chr hex $1/eg;                # decode
+    s/%([A-Fa-f\d]{2})/chr hex $1/eg;            # decode
 
 However, you should only apply them to individual URI components, not
 the entire URI, otherwise you'll lose information and generally mess