PerlFAQ sync.

p4raw-id: //depot/perl@19188

5 files changed, 108 insertions, 46 deletions

diff --git a/pod/perlfaq.pod b/pod/perlfaq.pod
index cc2c185bbf..7acdf613d0 100644
--- a/pod/perlfaq.pod
+++ b/pod/perlfaq.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq - frequently asked questions about Perl ($Date: 2003/01/26 17:45:46 $)
+perlfaq - frequently asked questions about Perl ($Date: 2003/01/31 17:37:17 $)
 
 =head1 DESCRIPTION
 
@@ -70,9 +70,33 @@ in respect of this information or its use.
 
 =head1 Table of Contents
 
-=head2 perlfaq: Structural overview of the FAQ.
+=over 4
+
+=item perlfaq  - this document
+
+=item perlfaq1 - General Questions About Perl
+
+=item perlfaq2 - Obtaining and Learning about Perl
+
+=item perlfaq3 - Programming Tools
+
+=item perlfaq4 - Data Manipulation
+
+=item perlfaq5 - Files and Formats
+
+=item perlfaq6 - Regular Expressions
+
+=item perlfaq7 - General Perl Language Issues
 
-This document.
+=item perlfaq8 - System Interaction
+
+=item perlfaq9 - Networking
+
+
+=back
+
+
+=head1 The Questions
 
 =head2 L<perlfaq1>: General Questions About Perl
 
@@ -412,7 +436,7 @@ How do I get a random number between X and Y?
 
 =item *
 
-How do I find the week-of-the-year/day-of-the-year?
+How do I find the day or week of the year?
 
 =item *
 
@@ -1050,6 +1074,10 @@ How do I clear a package?
 
 How can I use a variable as a variable name?
 
+=item *
+
+What does "bad interpreter" mean?
+
 =back
 
 
diff --git a/pod/perlfaq3.pod b/pod/perlfaq3.pod
index 7c7527edae..40e15de2ca 100644
--- a/pod/perlfaq3.pod
+++ b/pod/perlfaq3.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq3 - Programming Tools ($Revision: 1.32 $, $Date: 2003/01/26 17:41:53 $)
+perlfaq3 - Programming Tools ($Revision: 1.33 $, $Date: 2003/01/31 17:34:56 $)
 
 =head1 DESCRIPTION
 
@@ -466,45 +466,33 @@ module, which is curses-based, can help with this.
 
 The best way to do this is to come up with a better algorithm.  This
 can often make a dramatic difference.  Jon Bentley's book
-``Programming Pearls'' (that's not a misspelling!)  has some good tips
+I<Programming Pearls> (that's not a misspelling!)  has some good tips
 on optimization, too.  Advice on benchmarking boils down to: benchmark
 and profile to make sure you're optimizing the right part, look for
 better algorithms instead of microtuning your code, and when all else
 fails consider just buying faster hardware.  You will probably want to
-read the answer to the earlier question ``How do I profile my Perl programs?''
-if you haven't done so already.
+read the answer to the earlier question ``How do I profile my Perl
+programs?'' if you haven't done so already.
 
 A different approach is to autoload seldom-used Perl code.  See the
 AutoSplit and AutoLoader modules in the standard distribution for
 that.  Or you could locate the bottleneck and think about writing just
 that part in C, the way we used to take bottlenecks in C code and
-write them in assembler.  Similar to rewriting in C,
-modules that have critical sections can be written in C (for instance, the
-PDL module from CPAN).
-
-In some cases, it may be worth it to use the backend compiler to
-produce byte code (saving compilation time) or compile into C, which
-will certainly save compilation time and sometimes a small amount (but
-not much) execution time.  See the question about compiling your Perl
-programs for more on the compiler--the wins aren't as obvious as you'd
-hope.
-
-If you're currently linking your perl executable to a shared I<libc.so>,
-you can often gain a 10-25% performance benefit by rebuilding it to
-link with a static libc.a instead.  This will make a bigger perl
-executable, but your Perl programs (and programmers) may thank you for
-it.  See the F<INSTALL> file in the source distribution for more
-information.
-
-Unsubstantiated reports allege that Perl interpreters that use sfio
-outperform those that don't (for I/O intensive applications).  To try
-this, see the F<INSTALL> file in the source distribution, especially
-the ``Selecting File I/O mechanisms'' section.
-
-The undump program was an old attempt to speed up your Perl program
-by storing the already-compiled form to disk.  This is no longer
-a viable option, as it only worked on a few architectures, and
-wasn't a good solution anyway.
+write them in assembler.  Similar to rewriting in C, modules that have
+critical sections can be written in C (for instance, the PDL module
+from CPAN).
+
+If you're currently linking your perl executable to a shared
+I<libc.so>, you can often gain a 10-25% performance benefit by
+rebuilding it to link with a static libc.a instead.  This will make a
+bigger perl executable, but your Perl programs (and programmers) may
+thank you for it.  See the F<INSTALL> file in the source distribution
+for more information.
+
+The undump program was an ancient attempt to speed up Perl program by
+storing the already-compiled form to disk.  This is no longer a viable
+option, as it only worked on a few architectures, and wasn't a good
+solution anyway.
 
 =head2 How can I make my Perl program take less memory?
 
diff --git a/pod/perlfaq4.pod b/pod/perlfaq4.pod
index b641d5845e..818225bc67 100644
--- a/pod/perlfaq4.pod
+++ b/pod/perlfaq4.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq4 - Data Manipulation ($Revision: 1.40 $, $Date: 2003/01/26 17:43:21 $)
+perlfaq4 - Data Manipulation ($Revision: 1.43 $, $Date: 2003/02/23 20:25:09 $)
 
 =head1 DESCRIPTION
 
@@ -316,7 +316,7 @@ Get the http://www.cpan.org/modules/by-module/Roman module.
 If you're using a version of Perl before 5.004, you must call C<srand>
 once at the start of your program to seed the random number generator.
 
-	 BEGIN { srand() if $[ < 5.004 }
+	 BEGIN { srand() if $] < 5.004 }
 
 5.004 and later automatically call C<srand> at the beginning.  Don't
 call C<srand> more than once---you make your numbers less random, rather
@@ -353,13 +353,34 @@ C<random_int_in(50,120)>
 
 =head1 Data: Dates
 
-=head2 How do I find the week-of-the-year/day-of-the-year?
+=head2 How do I find the day or week of the year?
 
-The day of the year is in the array returned by localtime() (see
-L<perlfunc/"localtime">):
+The localtime function returns the day of the week.  Without an
+argument localtime uses the current time.
 
-    $day_of_year = (localtime(time()))[7];
+    $day_of_year = (localtime)[7];
+    
+The POSIX module can also format a date as the day of the year or
+week of the year.
 
+	use POSIX qw/strftime/;
+	my $day_of_year  = strftime "%j", localtime;
+	my $week_of_year = strftime "%W", localtime;
+
+To get the day of year for any date, use the Time::Local module to get
+a time in epoch seconds for the argument to localtime.
+	
+	use POSIX qw/strftime/;
+	use Time::Local;
+	my $week_of_year = strftime "%W", 
+		localtime( timelocal( 0, 0, 0, 18, 11, 1987 ) );
+
+The Date::Calc module provides two functions for to calculate these.
+
+	use Date::Calc;
+	my $day_of_year  = Day_of_Year(  1987, 12, 18 );
+	my $week_of_year = Week_of_Year( 1987, 12, 18 );
+	
 =head2 How do I find the current century or millennium?
 
 Use the following simple functions:
diff --git a/pod/perlfaq7.pod b/pod/perlfaq7.pod
index a144457de9..814a40314c 100644
--- a/pod/perlfaq7.pod
+++ b/pod/perlfaq7.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq7 - General Perl Language Issues ($Revision: 1.13 $, $Date: 2003/01/26 17:45:46 $)
+perlfaq7 - General Perl Language Issues ($Revision: 1.14 $, $Date: 2003/01/31 17:38:14 $)
 
 =head1 DESCRIPTION
 
@@ -879,6 +879,31 @@ subroutines, because they are always global--you can't use my() on them.
 For scalars, arrays, and hashes, though--and usually for subroutines--
 you probably only want to use hard references.
 
+=head2 What does "bad interpreter" mean?
+
+The "bad interpreter" message comes from the shell, not perl.  The
+actual message may vary depending on your platform, shell, and locale
+settings.
+
+If you see "bad interpreter - no such file or directory", the first
+line in your perl script (the "shebang" line) does not contain the
+right path to perl (or any other program capable of running scripts). 
+Sometimes this happens when you move the script from one machine to
+another and each machine has a different path to perl---/usr/bin/perl
+versus /usr/local/bin/perl for instance.
+
+If you see "bad interpreter: Permission denied", you need to make your
+script executable.
+
+In either case, you should still be able to run the scripts with perl
+explicitly:
+
+	% perl script.pl
+
+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.
+
 =head1 AUTHOR AND COPYRIGHT
 
 Copyright (c) 1997-2002 Tom Christiansen and Nathan Torkington.
diff --git a/pod/perlfaq9.pod b/pod/perlfaq9.pod
index ec0a4f5b74..f73c619b98 100644
--- a/pod/perlfaq9.pod
+++ b/pod/perlfaq9.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq9 - Networking ($Revision: 1.14 $, $Date: 2002/12/06 07:40:11 $)
+perlfaq9 - Networking ($Revision: 1.15 $, $Date: 2003/01/31 17:36:57 $)
 
 =head1 DESCRIPTION
 
@@ -557,17 +557,17 @@ SMTP via L<Net::SMTP>.
 =head2 How do I read mail?
 
 While you could use the Mail::Folder module from CPAN (part of the
-MailFolder package) or the Mail::Internet module from CPAN (also part
+MailFolder package) or the Mail::Internet module from CPAN (part
 of the MailTools package), often a module is overkill.  Here's a
 mail sorter.
 
     #!/usr/bin/perl
-    # bysub1 - simple sort by subject
+
     my(@msgs, @sub);
     my $msgno = -1;
     $/ = '';                    # paragraph reads
     while (<>) {
-        if (/^From/m) {
+        if (/^From /m) {
             /^Subject:\s*(?:Re:\s*)*(.*)/mi;
             $sub[++$msgno] = lc($1) || '';
         }