pod/perlfaq* update from Tom Christiansen <tchrist@perl.com>

p4raw-id: //depot/maint-5.005/perl@1745

6 files changed, 90 insertions, 66 deletions

diff --git a/pod/perlfaq.pod b/pod/perlfaq.pod
index 700fd10566..e6be112008 100644
--- a/pod/perlfaq.pod
+++ b/pod/perlfaq.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq - frequently asked questions about Perl ($Date: 1998/07/20 23:12:17 $)
+perlfaq - frequently asked questions about Perl ($Date: 1998/08/05 12:09:32 $)
 
 =head1 DESCRIPTION
 
diff --git a/pod/perlfaq1.pod b/pod/perlfaq1.pod
index ee071e4216..5a95f19c79 100644
--- a/pod/perlfaq1.pod
+++ b/pod/perlfaq1.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq1 - General Questions About Perl ($Revision: 1.14 $, $Date: 1998/06/14 22:15:25 $)
+perlfaq1 - General Questions About Perl ($Revision: 1.15 $, $Date: 1998/08/05 11:52:24 $)
 
 =head1 DESCRIPTION
 
@@ -29,7 +29,8 @@ distribution policy of perl.  Perl is supported by its users.  The
 core, the standard Perl library, the optional modules, and the
 documentation you're reading now were all written by volunteers.  See
 the personal note at the end of the README file in the perl source
-distribution for more details.
+distribution for more details.  See L<perlhist> (new as of 5.005)
+for Perl's milestone releases.
 
 In particular, the core development team (known as the Perl
 Porters) are a rag-tag band of highly altruistic individuals
@@ -51,10 +52,10 @@ users the informal support will more than suffice.  See the answer to
 
 You should definitely use version 5.  Version 4 is old, limited, and
 no longer maintained; its last patch (4.036) was in 1992.  The most
-recent production release is 5.004_01.  Further references to the Perl
+recent production release is 5.005_01.  Further references to the Perl
 language in this document refer to this production release unless
 otherwise specified.  There may be one or more official bug fixes for
-5.004_01 by the time you read this, and also perhaps some experimental
+5.005_01 by the time you read this, and also perhaps some experimental
 versions on the way to the next release.
 
 =head2 What are perl4 and perl5?
@@ -210,7 +211,7 @@ available from http://www.perl.com/CPAN/misc/japh .
 Over a hundred quips by Larry, from postings of his or source code,
 can be found at http://www.perl.com/CPAN/misc/lwall-quotes .
 
-=head2 How can I convince my sysadmin/supervisor/employees to use version (5/5.004/Perl instead of some other language)?
+=head2 How can I convince my sysadmin/supervisor/employees to use version (5/5.005/Perl instead of some other language)?
 
 If your manager or employees are wary of unsupported software, or
 software which doesn't officially ship with your Operating System, you
@@ -240,10 +241,15 @@ for any given task.  Also mention that the difference between version
 (Well, ok, maybe not quite that distinct, but you get the idea.)  If
 you want support and a reasonable guarantee that what you're
 developing will continue to work in the future, then you have to run
-the supported version.  That probably means running the 5.004 release,
-although 5.003 isn't that bad (it's just one year and one release
+the supported version.  That probably means running the 5.005 release,
+although 5.004 isn't that bad (it's just one year and one release
 behind).  Several important bugs were fixed from the 5.000 through
-5.002 versions, though, so try upgrading past them if possible.
+5.003 versions, though, so try upgrading past them if possible.
+
+Of particular note is the massive bughunt for buffer overflow
+problems that went into the 5.004 release.  All releases prior to
+that, including perl4, are considered insecure and should be upgraded
+as soon as possible. 
 
 =head1 AUTHOR AND COPYRIGHT
 
diff --git a/pod/perlfaq2.pod b/pod/perlfaq2.pod
index c743a0efc8..918e9369ae 100644
--- a/pod/perlfaq2.pod
+++ b/pod/perlfaq2.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.24 $, $Date: 1998/07/20 23:40:28 $)
+perlfaq2 - Obtaining and Learning about Perl ($Revision: 1.25 $, $Date: 1998/08/05 11:47:25 $)
 
 =head1 DESCRIPTION
 
@@ -11,22 +11,25 @@ related matters.
 =head2 What machines support Perl?  Where do I get it?
 
 The standard release of Perl (the one maintained by the perl
-development team) is distributed only in source code form.  You can
-find this at http://www.perl.com/CPAN/src/latest.tar.gz, which is a
-gzipped archive in POSIX tar format.  This source builds with no
-porting whatsoever on most Unix systems (Perl's native environment),
-as well as Plan 9, VMS, QNX, OS/2, and the Amiga.
-
-Although it's rumored that the (imminent) 5.004 release may build
-on Windows NT, this is yet to be proven.  Binary distributions
-for 32-bit Microsoft systems and for Apple systems can be found
-http://www.perl.com/CPAN/ports/ directory.  Because these are not part of
-the standard distribution, they may and in fact do differ from the base
-Perl port in a variety of ways.  You'll have to check their respective
-release notes to see just what the differences are.  These differences
-can be either positive (e.g. extensions for the features of the particular
-platform that are not supported in the source release of perl) or negative
-(e.g. might be based upon a less current source release of perl).
+development team) is distributed only in source code form.  You
+can find this at http://www.perl.com/CPAN/src/latest.tar.gz, which
+in standard Internet format (a gzipped archive in POSIX tar format).
+
+Perl builds and runs on a bewildering number of platforms.  Virtually
+all known and current Unix derivatives are supported (Perl's native
+platform), as are proprietary systems like VMS, DOS, OS/2, Windows,
+QNX, BeOS, and the Amiga.  There are also the beginnings of support
+for MPE/iX.
+
+Binary distributions for some proprietary platforms, including
+Apple systems can be found http://www.perl.com/CPAN/ports/ directory.
+Because these are not part of the standard distribution, they may
+and in fact do differ from the base Perl port in a variety of ways.
+You'll have to check their respective release notes to see just
+what the differences are.  These differences can be either positive
+(e.g. extensions for the features of the particular platform that
+are not supported in the source release of perl) or negative (e.g.
+might be based upon a less current source release of perl).
 
 A useful FAQ for Win32 Perl users is
 http://www.endcontsw.com/people/evangelo/Perl_for_Win32_FAQ.html
@@ -177,25 +180,41 @@ these are good, some are ok, but many aren't worth your money.  Tom
 Christiansen maintains a list of these books, some with extensive
 reviews, at http://www.perl.com/perl/critiques/index.html.
 
-The incontestably definitive reference book on Perl, written by the
-creator of Perl and his apostles, is now in its second edition and
-fourth printing.
+The incontestably definitive reference book on Perl, written by
+the creator of Perl, is now in its second edition:
 
     Programming Perl (the "Camel Book"):
 	Authors: Larry Wall, Tom Christiansen, and Randal Schwartz
         ISBN 1-56592-149-6      (English)
         ISBN 4-89052-384-7      (Japanese)
-	(French, German, and Italian translations also available)
+	URL: http://www.oreilly.com/catalog/pperl2/
+    (French, German, Italian, and Hungarian translations also
+    available)
 
-Note that O'Reilly books are color-coded: turquoise (some would call
-it teal) covers indicate perl5 coverage, while magenta (some would
-call it pink) covers indicate perl4 only.  Check the cover color
-before you buy!
+The companion volume to the Camel containing thousands
+of real-world examples, mini-tutorials, and complete programs
+(first premiering at the 1998 Perl Conference), is:
+
+    The Perl Cookbook (the "Ram Book"):
+	Authors: Tom Christiansen and Nathan Torkington, 
+		    with Foreword by Larry Wall
+	ISBN: 1-56592-243-3
+	URL:  http://perl.oreilly.com/cookbook/
 
 If you're already a hard-core systems programmer, then the Camel Book
 might suffice for you to learn Perl from.  But if you're not, check
-out I<Learning Perl> by Randal and Tom.  The second edition of "Llama
-Book" has a blue cover, and is updated for the 5.004 release of Perl.
+out:
+
+    Learning Perl (the "Llama Book"):
+	Authors: Randal Schwartz and Tom Christiansen 
+		    with Foreword by Larry Wall
+	ISBN: 1-56592-284-0
+	URL:  http://www.oreilly.com/catalog/lperl2/
+
+Despite the picture at the URL above, the second edition of "Llama
+Book" really has a blue cover, and is updated for the 5.004 release
+of Perl.  Various foreign language editions are available, including
+I<Learning Perl on Win32 Systems> (the Gecko Book).
 
 If you're not an accidental programmer, but a more serious and possibly
 even degreed computer scientist who doesn't need as much hand-holding as
@@ -211,8 +230,8 @@ See http://www.ora.com/ on the Web.
 What follows is a list of the books that the FAQ authors found personally
 useful.  Your mileage may (but, we hope, probably won't) vary.
 
-Recommended books on (or muchly on) Perl are the following.  
-Those marked with a star may be ordered from O'Reilly.
+Recommended books on (or muchly on) Perl follow; those marked with
+a star may be ordered from O'Reilly.
 
 =over
 
@@ -228,6 +247,7 @@ Those marked with a star may be ordered from O'Reilly.
 		
     *Learning Perl [2nd edition]
 	by Randal L. Schwartz and Tom Christiansen
+	    with foreword by Larry Wall
 
     *Learning Perl on Win32 Systems
 	by Randal L. Schwartz, Erik Olson, and Tom Christiansen,
@@ -273,9 +293,10 @@ The first and only periodical devoted to All Things Perl, I<The
 Perl Journal> contains tutorials, demonstrations, case studies,
 announcements, contests, and much more.  TPJ has columns on web
 development, databases, Win32 Perl, graphical programming, regular
-expressions, and networking, and sponsors the Obfuscated Perl Contest.
-It is published quarterly by Jon Orwant.  See http://www.tpj.com/ or
-send mail to subscriptions@tpj.com.
+expressions, and networking, and sponsors the Obfuscated Perl
+Contest.  It is published quarterly under the gentle hand of its
+editor, Jon Orwant.  See http://www.tpj.com/ or send mail to
+subscriptions@tpj.com.
 
 Beyond this, magazines that frequently carry high-quality articles
 on Perl are I<Web Techniques> (see http://www.webtechniques.com/),
@@ -297,9 +318,6 @@ following list is I<not> the complete list of CPAN mirrors.
   http://www.cs.ruu.nl/pub/PERL/CPAN/
   ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
 
-http:/www.oasis.leo.org/perl/ has, amongst other things, source to
-versions 1 through 5 of Perl.
-
 =head2 What mailing lists are there for perl?
 
 Most of the major modules (tk, CGI, libwww-perl) have their own
@@ -427,6 +445,8 @@ For more information, contact the The Perl Clinic:
     Web:    http://www.perl.co.uk/
     Email:  perl-support-info@perl.co.uk or Tim.Bunce@ig.co.uk
 
+See also www.perl.com for updates on training and support.
+
 =head2 Where do I send bug reports?
 
 If you are reporting a bug in the perl interpreter or the modules
@@ -443,7 +463,7 @@ Read the perlbug(1) man page (perl5.004 or later) for more information.
 
 =head2 What is perl.com?  perl.org?  The Perl Institute?
 
-The perl.com domain is Tom Christiansen's domain.  He created it as a
+The perl.com domain is managed by Tom Christiansen, who created it as a
 public service long before perl.org came about.  Despite the name, it's a
 pretty non-commercial site meant to be a clearinghouse for information
 about all things Perlian, accepting no paid advertisements, bouncy
@@ -454,9 +474,7 @@ Systems, a software-oriented subsidiary of O'Reilly and Associates.
 perl.org is the official vehicle for The Perl Institute.  The motto of
 TPI is "helping people help Perl help people" (or something like
 that).  It's a non-profit organization supporting development,
-documentation, and dissemination of perl.  Current directors of TPI
-include Larry Wall, Tom Christiansen, and Randal Schwartz, whom you
-may have heard of somewhere else around here.
+documentation, and dissemination of perl.  
 
 =head2 How do I learn about object-oriented Perl programming?
 
diff --git a/pod/perlfaq3.pod b/pod/perlfaq3.pod
index 11f105c48c..d06f2bef7a 100644
--- a/pod/perlfaq3.pod
+++ b/pod/perlfaq3.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq3 - Programming Tools ($Revision: 1.28 $, $Date: 1998/07/16 22:08:49 $)
+perlfaq3 - Programming Tools ($Revision: 1.29 $, $Date: 1998/08/05 11:57:04 $)
 
 =head1 DESCRIPTION
 
@@ -372,10 +372,10 @@ you want to be sure your licence's wording will stand up in court.
 =head2 How can I compile my Perl program into byte code or C?
 
 Malcolm Beattie has written a multifunction backend compiler,
-available from CPAN, that can do both these things.  It is as of
-Jul-1998 in late alpha release, which means it's fun to play with if
-you're a programmer but not really for people looking for turn-key
-solutions.
+available from CPAN, that can do both these things.  It is included
+in the perl5.005 release, but is still considered experimental.
+This means it's fun to play with if you're a programmer but not
+really for people looking for turn-key solutions.
 
 Merely compiling into C does not in and of itself guarantee that your
 code will run very much faster.  That's because except for lucky cases
@@ -386,11 +386,6 @@ compilation time, leaving execution no more than 10-30% faster.  A few
 rare programs actually benefit significantly (like several times
 faster), but this takes some tweaking of your code.
 
-The 5.005 release of Perl itself, whose main goal is merging the various
-non-Unix ports back into the one Perl source, will also have preliminary
-(strictly beta) support for Malcolm's compiler and his light-weight
-processes (sometimes called ``threads'').
-
 You'll probably be astonished to learn that the current version of the
 compiler generates a compiled form of your script whose executable is
 just as big as the original perl executable, and then some.  That's
@@ -410,7 +405,7 @@ and compilation never stopped software piracy in the form of crackers,
 viruses, or bootleggers.  The real advantage of the compiler is merely
 packaging, and once you see the size of what it makes (well, unless
 you use a shared I<libperl.so>), you'll probably want a complete
-Perl install anywayt.
+Perl install anyway.
 
 =head2 How can I get C<#!perl> to work on [MS-DOS,NT,...]?
 
diff --git a/pod/perlfaq4.pod b/pod/perlfaq4.pod
index 0a47145a28..633f5f109b 100644
--- a/pod/perlfaq4.pod
+++ b/pod/perlfaq4.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq4 - Data Manipulation ($Revision: 1.25 $, $Date: 1998/07/16 22:49:55 $)
+perlfaq4 - Data Manipulation ($Revision: 1.26 $, $Date: 1998/08/05 12:04:00 $)
 
 =head1 DESCRIPTION
 
@@ -177,7 +177,11 @@ You can find the week of the year by dividing this by 7:
 
 Of course, this believes that weeks start at zero.  The Date::Calc
 module from CPAN has a lot of date calculation functions, including
-day of the year, week of the year, and so on. 
+day of the year, week of the year, and so on.   Note that not
+all business consider ``week 1'' to be the same; for example,
+American business often consider the first week with a Monday
+in it to be Work Week #1, despite ISO 8601, which consider 
+WW1 to be the frist week with a Thursday in it.
 
 =head2 How can I compare two dates and find the difference?
 
@@ -202,8 +206,9 @@ http://www.perl.com/CPAN/authors/David_Muir_Sharnoff/modules/Time/JulianDay.pm.g
 
 =head2 Does Perl have a year 2000 problem?  Is Perl Y2K compliant?
 
-Short answer: No, Perl does not have a Year 2000 problem.  Yes, Perl
-is Y2K compliant.
+Short answer: No, Perl does not have a Year 2000 problem.  Yes,
+Perl is Y2K compliant.  The programmers you're hired to use it,
+however, probably are not.
 
 Long answer: Perl is just as Y2K compliant as your pencil--no more,
 and no less.  The date and time functions supplied with perl (gmtime
@@ -471,7 +476,7 @@ Or more nicely written as:
 	s/\s+$//;
     }
 
-This idiom takes advantage of the C<for(each)> loop's aliasing
+This idiom takes advantage of the C<foreach> loop's aliasing
 behavior to factor out common code.  You can do this
 on several strings at once, or arrays, or even the 
 values of a hash if you use a slide:
diff --git a/pod/perlfaq8.pod b/pod/perlfaq8.pod
index e99cf426ca..c4036ff35d 100644
--- a/pod/perlfaq8.pod
+++ b/pod/perlfaq8.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq8 - System Interaction ($Revision: 1.25 $, $Date: 1998/07/05 15:07:20 $)
+perlfaq8 - System Interaction ($Revision: 1.26 $, $Date: 1998/08/05 12:20:28 $)
 
 =head1 DESCRIPTION
 
@@ -1005,7 +1005,7 @@ Perl offers several different ways to include code from one file into
 another.  Here are the deltas between the various inclusion constructs:
 
     1)  do $file is like eval `cat $file`, except the former:
-	1.1: searches @INC.
+	1.1: searches @INC and updates %INC.
 	1.2: bequeaths an *unrelated* lexical scope on the eval'ed code.
 
     2)  require $file is like do $file, except the former: