FAQ sync.

p4raw-id: //depot/perl@12274

4 files changed, 128 insertions, 62 deletions

diff --git a/pod/perlfaq3.pod b/pod/perlfaq3.pod
index 0a1e42acd7..9979ab9e7c 100644
--- a/pod/perlfaq3.pod
+++ b/pod/perlfaq3.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq3 - Programming Tools ($Revision: 1.1 $, $Date: 2001/09/20 03:03:00 $)
+perlfaq3 - Programming Tools ($Revision: 1.2 $, $Date: 2001/09/29 03:13:13 $)
 
 =head1 DESCRIPTION
 
@@ -474,6 +474,56 @@ Information about malloc is in the F<INSTALL> file in the source
 distribution.  You can find out whether you are using perl's malloc by
 typing C<perl -V:usemymalloc>.
 
+Of course, the best way to save memory is to not do anything to waste
+it in the first place. Good programming practices can go a long way
+toward this:
+
+=over 4
+
+=item * Don't slurp!
+
+Don't read an entire file into memory if you can process it line
+by line. Or more concretely, use a loop like this:
+
+	#
+	# Good Idea
+	#
+	while (<FILE>) {
+	   # ...
+	}
+
+instead of this:
+
+	#
+	# Bad Idea
+	#
+	@data = <FILE>;
+	foreach (@data) {
+	    # ...
+	}
+
+When the files you're processing are small, it doesn't much matter which
+way you do it, but it makes a huge difference when they start getting
+larger. 
+
+=item * Pass by reference
+
+Pass arrays and hashes by reference, not by value. For one thing, it's
+the only way to pass multiple lists or hashes (or both) in a single
+call/return. It also avoids creating a copy of all the contents. This
+requires some judgment, however, because any changes will be propagated
+back to the original data. If you really want to mangle (er, modify) a
+copy, you'll have to sacrifice the memory needed to make one.
+
+=item * Tie large variables to disk.
+
+For "big" data stores (i.e. ones that exceed available memory) consider
+using one of the DB modules to store it on disk instead of in RAM. This
+will incur a penalty in access time, but that's probably better that
+causing your hard disk to thrash due to massive swapping.
+
+=back
+
 =head2 Is it unsafe to return a pointer to local data?
 
 No, Perl's garbage collection system takes care of this.
diff --git a/pod/perlfaq4.pod b/pod/perlfaq4.pod
index 4e574e917b..72eb8d8dee 100644
--- a/pod/perlfaq4.pod
+++ b/pod/perlfaq4.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq4 - Data Manipulation ($Revision: 1.1 $, $Date: 2001/09/20 03:03:00 $)
+perlfaq4 - Data Manipulation ($Revision: 1.2 $, $Date: 2001/09/26 15:42:12 $)
 
 =head1 DESCRIPTION
 
@@ -583,7 +583,7 @@ To make the first letter of each word upper case:
 
 This has the strange effect of turning "C<don't do it>" into "C<Don'T
 Do It>".  Sometimes you might want this.  Other times you might need a
-more thorough solution (Suggested by brian d.  foy):
+more thorough solution (Suggested by brian d foy):
 
     $string =~ s/ (
                  (^\w)    #at the beginning of the line
diff --git a/pod/perlfaq5.pod b/pod/perlfaq5.pod
index 85b9f6a995..bfd6d35494 100644
--- a/pod/perlfaq5.pod
+++ b/pod/perlfaq5.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq5 - Files and Formats ($Revision: 1.1 $, $Date: 2001/09/20 03:03:00 $)
+perlfaq5 - Files and Formats ($Revision: 1.2 $, $Date: 2001/09/26 10:44:41 $)
 
 =head1 DESCRIPTION
 
@@ -428,9 +428,9 @@ See L<perlform/"Accessing Formatting Internals"> for an swrite() function.
 This one will do it for you:
 
     sub commify {
-	local $_  = shift;
-	1 while s/^([-+]?\d+)(\d{3})/$1,$2/;
-	return $_;
+        my $number = shift;
+	1 while ($number =~ s/^([-+]?\d+)(\d{3})/$1,$2/);
+	return $number;
     }
 
     $n = 23659019423.2331;
diff --git a/pod/perlfaq9.pod b/pod/perlfaq9.pod
index 892772e015..3bf862f3eb 100644
--- a/pod/perlfaq9.pod
+++ b/pod/perlfaq9.pod
@@ -1,45 +1,66 @@
 =head1 NAME
 
-perlfaq9 - Networking ($Revision: 1.1 $, $Date: 2001/09/20 03:03:00 $)
+perlfaq9 - Networking ($Revision: 1.2 $, $Date: 2001/09/28 06:40:07 $)
 
 =head1 DESCRIPTION
 
 This section deals with questions related to networking, the internet,
 and a few on the web.
 
-=head2 My CGI script runs from the command line but not the browser.  (500 Server Error)
+=head2 What is the correct form of response from a CGI script?
 
-If you can demonstrate that you've read the following FAQs and that
-your problem isn't something simple that can be easily answered, you'll
-probably receive a courteous and useful reply to your question if you
-post it on comp.infosystems.www.authoring.cgi (if it's something to do
-with HTTP, HTML, or the CGI protocols).  Questions that appear to be Perl
-questions but are really CGI ones that are posted to comp.lang.perl.misc
-may not be so well received.
+(Alan Flavell <flavell+www@a5.ph.gla.ac.uk> answers...)
 
-The useful FAQs and related documents are:
+The Common Gateway Interface (CGI) specifies a software interface between 
+a program ("CGI script") and a web server (HTTPD). It is not specific 
+to Perl, and has its own FAQs and tutorials, and usenet group, 
+comp.infosystems.www.authoring.cgi 
 
-    CGI FAQ
-        http://www.webthing.com/tutorials/cgifaq.html
+The original CGI specification is at: http://hoohoo.ncsa.uiuc.edu/cgi/ 
 
-    Web FAQ
-        http://www.boutell.com/faq/
+Current best-practice RFC draft at: http://CGI-Spec.Golux.Com/ 
 
-    WWW Security FAQ
-        http://www.w3.org/Security/Faq/
+Other relevant documentation listed in: http://www.perl.org/CGI_MetaFAQ.html
 
-    HTTP Spec
-        http://www.w3.org/pub/WWW/Protocols/HTTP/
+These Perl FAQs very selectively cover some CGI issues. However, Perl 
+programmers are strongly advised to use the CGI.pm module, to take care
+of the details for them. 
 
-    HTML Spec
-        http://www.w3.org/TR/REC-html40/
-        http://www.w3.org/pub/WWW/MarkUp/
+The similarity between CGI response headers (defined in the CGI
+specification) and HTTP response headers (defined in the HTTP
+specification, RFC2616) is intentional, but can sometimes be confusing.
 
-    CGI Spec
-        http://www.w3.org/CGI/
+The CGI specification defines two kinds of script: the "Parsed Header"
+script, and the "Non Parsed Header" (NPH) script. Check your server
+documentation to see what it supports. "Parsed Header" scripts are
+simpler in various respects. The CGI specification allows any of the
+usual newline representations in the CGI response (it's the server's
+job to create an accurate HTTP response based on it). So "\n" written in
+text mode is technically correct, and recommended. NPH scripts are more
+tricky: they must put out a complete and accurate set of HTTP
+transaction response headers; the HTTP specification calls for records
+to be terminated with carriage-return and line-feed, i.e ASCII \015\012
+written in binary mode.
+
+Using CGI.pm gives excellent platform independence, including EBCDIC
+systems. CGI.pm selects an appropriate newline representation
+($CGI::CRLF) and sets binmode as appropriate.
+
+=head2 My CGI script runs from the command line but not the browser.  (500 Server Error)
+
+If you can demonstrate that you've read the FAQs and that 
+your problem isn't something simple that can be easily answered, you'll
+probably receive a courteous and useful reply to your question if you
+post it on comp.infosystems.www.authoring.cgi (if it's something to do
+with HTTP or the CGI protocols).  Questions that appear to be Perl
+questions but are really CGI ones that are posted to comp.lang.perl.misc
+are not so well received.
+
+The useful FAQs, related documents, and troubleshooting guides are 
+listed in the CGI Meta FAQ:
+
+	http://www.perl.org/CGI_MetaFAQ.html
 
-    CGI Security FAQ
-        http://www.go2net.com/people/paulp/cgi-security/safe-cgi.txt
 
 =head2 How can I get better error messages from a CGI program?
 
@@ -233,34 +254,36 @@ regexp for breaking any arbitrary URI into components (Appendix B).
 
 =head2 How do I redirect to another page?
 
-According to RFC 2616, "Hypertext Transfer Protocol -- HTTP/1.1", the
-preferred method is to send a C<Location:> header instead of a
-C<Content-Type:> header:
+Specify the complete URL of the destination (even if it is on the same
+server). This is one of the two different kinds of CGI "Location:"
+responses which are defined in the CGI specification for a Parsed Headers
+script. The other kind (an absolute URLpath) is resolved internally to
+the server without any HTTP redirection. The CGI specifications do not
+allow relative URLs in either case.
 
-    Location: http://www.domain.com/newpage
+Use of CGI.pm is strongly recommended.  This example shows redirection
+with a complete URL. This redirection is handled by the web browser.
 
-Note that relative URLs in these headers can cause strange effects
-because of "optimizations" that servers do.
+      use CGI qw/:standard/;
 
-    $url = "http://www.perl.com/CPAN/";
-    print "Location: $url\n\n";
-    exit;
+      my $url = 'http://www.perl.com/CPAN/';
+      print redirect($url);
 
-To target a particular frame in a frameset, include the "Window-target:"
-in the header.
 
-    print <<EOF;
-    Location: http://www.domain.com/newpage
-    Window-target: <FrameName>
+This example shows a redirection with an absolute URLpath.  This
+redirection is handled by the local web server.
 
-    EOF
+      my $url = '/CPAN/index.html';
+      print redirect($url);
+
+
+But if coded directly, it could be as follows (the final "\n" is 
+shown separately, for clarity), using either a complete URL or
+an absolute URLpath. 
+
+      print "Location: $url\n";   # CGI response header
+      print "\n";                 # end of headers
 
-To be correct to the spec, each of those virtual newlines should
-really be physical C<"\015\012"> sequences by the time your message is
-received by the client browser.  Except for NPH scripts, though, that
-local newline should get translated by your server into standard form,
-so you shouldn't have a problem here, even if you are stuck on MacOS.
-Everybody else probably won't even notice.
 
 =head2 How do I put a password on my web pages?
 
@@ -282,16 +305,9 @@ a DBI compatible driver.  HTTPD::UserAdmin supports files used by the
 
 =head2 How do I make sure users can't enter values into a form that cause my CGI script to do bad things?
 
-Read the CGI security FAQ, at
-http://www-genome.wi.mit.edu/WWW/faqs/www-security-faq.html , and the
-Perl/CGI FAQ at
-http://www.perl.com/CPAN/doc/FAQs/cgi/perl-cgi-faq.html .
+See the security references listed in the CGI Meta FAQ
 
-In brief: use tainting (see L<perlsec>), which makes sure that data
-from outside your script (eg, CGI parameters) are never used in
-C<eval> or C<system> calls.  In addition to tainting, never use the
-single-argument form of system() or exec().  Instead, supply the
-command and arguments as a list, which prevents shell globbing.
+	http://www.perl.org/CGI_MetaFAQ.html
 
 =head2 How do I parse a mail header?