FAQ sync

p4raw-id: //depot/perl@29034

8 files changed, 316 insertions, 116 deletions

diff --git a/pod/perlfaq.pod b/pod/perlfaq.pod
index 3ddb3e23d7..c75da2e27b 100644
--- a/pod/perlfaq.pod
+++ b/pod/perlfaq.pod
@@ -24,8 +24,8 @@ at http://faq.perl.org/ . The perlfaq-workers periodically post extracts
 of the latest perlfaq to comp.lang.perl.misc.
 
 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
+https://svn.perl.org/modules/perlfaq/trunk/ (which is outside of the
+main Perl source tree).  The SVN 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.
@@ -458,7 +458,7 @@ How do I find yesterday's date?
 
 =item *
 
-Does Perl have a Year 2000 problem?  Is Perl Y2K compliant?
+Does Perl have a Year 2000 problem? Is Perl Y2K compliant?
 
 =item *
 
@@ -707,7 +707,7 @@ How do I flush/unbuffer an output filehandle?  Why must I do this?
 
 =item *
 
-How do I change one line in a file/delete a line in a file/insert a line in the middle of a file/append to the beginning of a file?
+How do I change, delete, or insert a line in a file, or append to the beginning of a file?
 
 =item *
 
@@ -1323,7 +1323,7 @@ How do I download a file from the user's machine?  How do I open a file on anoth
 
 =item *
 
-How do I make a pop-up menu in HTML?
+How do I make an HTML pop-up menu with Perl?
 
 =item *
 
diff --git a/pod/perlfaq2.pod b/pod/perlfaq2.pod
index 00ab474559..31c1b2c17a 100644
--- a/pod/perlfaq2.pod
+++ b/pod/perlfaq2.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq2 - Obtaining and Learning about Perl ($Revision: 6750 $)
+perlfaq2 - Obtaining and Learning about Perl ($Revision: 7861 $)
 
 =head1 DESCRIPTION
 
@@ -90,46 +90,46 @@ architecture.
 
 =head2 What modules and extensions are available for Perl?  What is CPAN?  What does CPAN/src/... mean?
 
-CPAN stands for Comprehensive Perl Archive Network, a ~1.2Gb archive
-replicated on nearly 200 machines all over the world.  CPAN contains
-source code, non-native ports, documentation, scripts, and many
-third-party modules and extensions, designed for everything from
+CPAN stands for Comprehensive Perl Archive Network, a multi-gigabyte
+archive replicated on hundreds of machines all over the world. CPAN
+contains source code, non-native ports, documentation, scripts, and
+many third-party modules and extensions, designed for everything from
 commercial database interfaces to keyboard/screen control to web
-walking and CGI scripts.  The master web site for CPAN is
+walking and CGI scripts. The master web site for CPAN is
 http://www.cpan.org/ and there is the CPAN Multiplexer at
-http://www.cpan.org/CPAN.html which will choose a mirror near you
-via DNS.  See http://www.perl.com/CPAN (without a slash at the
-end) for how this process works. Also, http://mirror.cpan.org/
-has a nice interface to the http://www.cpan.org/MIRRORED.BY
-mirror directory.
+http://www.cpan.org/CPAN.html which will choose a mirror near you via
+DNS.  See http://www.perl.com/CPAN (without a slash at the end) for
+how this process works. Also, http://mirror.cpan.org/ has a nice
+interface to the http://www.cpan.org/MIRRORED.BY mirror directory.
 
-See the CPAN FAQ at http://www.cpan.org/misc/cpan-faq.html for
-answers to the most frequently asked questions about CPAN
-including how to become a mirror.
+See the CPAN FAQ at http://www.cpan.org/misc/cpan-faq.html for answers
+to the most frequently asked questions about CPAN including how to
+become a mirror.
 
 CPAN/path/... is a naming convention for files available on CPAN
 sites.  CPAN indicates the base directory of a CPAN mirror, and the
-rest of the path is the path from that directory to the file.  For
+rest of the path is the path from that directory to the file. For
 instance, if you're using ftp://ftp.funet.fi/pub/languages/perl/CPAN
 as your CPAN site, the file CPAN/misc/japh is downloadable as
 ftp://ftp.funet.fi/pub/languages/perl/CPAN/misc/japh .
 
-Considering that there are close to two thousand existing modules in
-the archive, one probably exists to do nearly anything you can think of.
-Current categories under CPAN/modules/by-category/ include Perl core
-modules; development support; operating system interfaces; networking,
-devices, and interprocess communication; data type utilities; database
-interfaces; user interfaces; interfaces to other languages; filenames,
-file systems, and file locking; internationalization and locale; world
-wide web support; server and daemon utilities; archiving and
-compression; image manipulation; mail and news; control flow
-utilities; filehandle and I/O; Microsoft Windows modules; and
-miscellaneous modules.
+Considering that, as of 2006, there are over ten thousand existing
+modules in the archive, one probably exists to do nearly anything you
+can think of. Current categories under CPAN/modules/by-category/
+include Perl core modules; development support; operating system
+interfaces; networking, devices, and interprocess communication; data
+type utilities; database interfaces; user interfaces; interfaces to
+other languages; filenames, file systems, and file locking;
+internationalization and locale; world wide web support; server and
+daemon utilities; archiving and compression; image manipulation; mail
+and news; control flow utilities; filehandle and I/O; Microsoft
+Windows modules; and miscellaneous modules.
 
 See http://www.cpan.org/modules/00modlist.long.html or
-http://search.cpan.org/ for a more complete list of modules by category.
+http://search.cpan.org/ for a more complete list of modules by
+category.
 
-CPAN is not affiliated with O'Reilly Media.
+CPAN is a free service and is not affiliated with O'Reilly Media.
 
 =head2 Is there an ISO or ANSI certified version of Perl?
 
@@ -501,9 +501,9 @@ the I<What is CPAN?> question earlier in this document.
 
 =head1 REVISION
 
-Revision: $Revision: 6750 $
+Revision: $Revision: 7861 $
 
-Date: $Date: 2006-08-06 02:30:54 +0200 (dim, 06 aoû 2006) $
+Date: $Date: 2006-09-29 22:19:18 +0200 (ven, 29 sep 2006) $
 
 See L<perlfaq> for source control details and availability.
 
diff --git a/pod/perlfaq3.pod b/pod/perlfaq3.pod
index 18f1345ce0..028461c970 100644
--- a/pod/perlfaq3.pod
+++ b/pod/perlfaq3.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq3 - Programming Tools ($Revision: 7822 $)
+perlfaq3 - Programming Tools ($Revision: 7875 $)
 
 =head1 DESCRIPTION
 
@@ -877,13 +877,13 @@ or Plan9 systems.  You might also have to change a single % to a %%.
 
 For example:
 
-    # Unix
+    # Unix (including Mac OS X)
     perl -e 'print "Hello world\n"'
 
     # DOS, etc.
     perl -e "print \"Hello world\n\""
 
-    # Mac
+    # Mac Classic
     print "Hello world\n"
      (then Run "Myscript" or Shift-Command-R)
 
@@ -929,7 +929,7 @@ A good place to start is L<perltoot>, and you can use L<perlobj>,
 L<perlboot>, L<perltoot>, L<perltooc>, and L<perlbot> for reference.
 
 A good book on OO on Perl is the "Object-Oriented Perl"
-by Damian Conway from Manning Publications, or "Intermediate Perl" 
+by Damian Conway from Manning Publications, or "Intermediate Perl"
 by Randal Schwartz, brian d foy, and Tom Phoenix from O'Reilly Media.
 
 =head2 Where can I learn about linking C with Perl?
@@ -982,9 +982,9 @@ to process and install a Perl distribution.
 
 =head1 REVISION
 
-Revision: $Revision: 7822 $
+Revision: $Revision: 7875 $
 
-Date: $Date: 2006-09-11 14:22:59 +0200 (lun, 11 sep 2006) $
+Date: $Date: 2006-10-04 22:39:26 +0200 (mer, 04 oct 2006) $
 
 See L<perlfaq> for source control details and availability.
 
diff --git a/pod/perlfaq4.pod b/pod/perlfaq4.pod
index e9c4ab316a..38a0e91328 100644
--- a/pod/perlfaq4.pod
+++ b/pod/perlfaq4.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq4 - Data Manipulation ($Revision: 6816 $)
+perlfaq4 - Data Manipulation ($Revision: 7954 $)
 
 =head1 DESCRIPTION
 
@@ -600,7 +600,9 @@ anonymous array. In this case, we call the function in list context.
 If we want to call the function in scalar context, we have to do a bit
 more work. We can really have any code we like inside the braces, so
 we simply have to end with the scalar reference, although how you do
-that is up to you, and you can use code inside the braces.
+that is up to you, and you can use code inside the braces. Note that
+the use of parens creates a list context, so we need C<scalar> to
+force the scalar context on the function:
 
 	print "The time is ${\(scalar localtime)}.\n"
 
@@ -958,25 +960,39 @@ Left and right padding with any character, modifying C<$text> directly:
 
 =head2 How do I extract selected columns from a string?
 
-Use C<substr()> or C<unpack()>, both documented in L<perlfunc>.
-If you prefer thinking in terms of columns instead of widths,
-you can use this kind of thing:
-
-	# determine the unpack format needed to split Linux ps output
-	# arguments are cut columns
-	my $fmt = cut2fmt(8, 14, 20, 26, 30, 34, 41, 47, 59, 63, 67, 72);
-
-	sub cut2fmt {
-		my(@positions) = @_;
-		my $template  = '';
-		my $lastpos   = 1;
-		for my $place (@positions) {
-			$template .= "A" . ($place - $lastpos) . " ";
-			$lastpos   = $place;
-			}
-		$template .= "A*";
-		return $template;
-		}
+(contributed by brian d foy)
+
+If you know where the columns that contain the data, you can
+use C<substr> to extract a single column.
+
+	my $column = substr( $line, $start_column, $length );
+
+You can use C<split> if the columns are separated by whitespace or
+some other delimiter, as long as whitespace or the delimiter cannot
+appear as part of the data.
+
+	my $line    = ' fred barney   betty   ';
+	my @columns = split /\s+/, $line;
+		# ( '', 'fred', 'barney', 'betty' );
+
+	my $line    = 'fred||barney||betty';
+	my @columns = split /\|/, $line;
+		# ( 'fred', '', 'barney', '', 'betty' );
+
+If you want to work with comma-separated values, don't do this since
+that format is a bit more complicated. Use one of the modules that
+handle that fornat, such as C<Text::CSV>, C<Text::CSV_XS>, or
+C<Text::CSV_PP>.
+
+If you want to break apart an entire line of fixed columns, you can use
+C<unpack> with the A (ASCII) format. by using a number after the format
+specifier, you can denote the column width. See the C<pack> and C<unpack>
+entries in L<perlfunc> for more details.
+
+	my @fields = unpack( $line, "A8 A8 A8 A16 A4" );
+
+Note that spaces in the format argument to C<unpack> do not denote literal
+spaces. If you have space separated data, you may want C<split> instead.
 
 =head2 How do I find the soundex value of a string?
 
@@ -988,37 +1004,52 @@ C<Text::Metaphone>, and C<Text::DoubleMetaphone> modules.
 
 =head2 How can I expand variables in text strings?
 
-Let's assume that you have a string that contains placeholder
-variables.
-
-	$text = 'this has a $foo in it and a $bar';
-
-You can use a substitution with a double evaluation.  The
-first /e turns C<$1> into C<$foo>, and the second /e turns
-C<$foo> into its value.  You may want to wrap this in an
-C<eval>: if you try to get the value of an undeclared variable
-while running under C<use strict>, you get a fatal error.
-
-	eval { $text =~ s/(\$\w+)/$1/eeg };
-	die if $@;
-
-It's probably better in the general case to treat those
-variables as entries in some special hash.  For example:
+(contributed by brian d foy)
 
-	%user_defs = (
-		foo  => 23,
-		bar  => 19,
+For example, I'll use a string that has two Perl scalar variables
+in it. In this example, I want to expand C<$foo> and C<$bar> to
+their variable's values.
+
+	my $foo = 'Fred';
+	my $bar = 'Barney';
+	$string = 'Say hello to $foo and $bar';
+
+One way I can do this involves the substitution operator and a double
+C</e> flag.  The first C</e> evaluates C<$1> on the replacement side and
+turns it into C<$foo>. The second /e starts with C<$foo> and replaces
+it with its value. C<$foo>, then, turns into 'Fred', and that's finally
+what's left in the string.
+
+	$string =~ s/(\$\w+)/$1/eeg; # 'Say hello to Fred and Barney'
+	
+The C</e> will also silently ignore violations of strict, replacing
+undefined variable names with the empty string.
+
+I could also pull the values from a hash instead of evaluating 
+variable names. Using a single C</e>, I can check the hash to ensure
+the value exists, and if it doesn't, I can replace the missing value
+with a marker, in this case C<???> to signal that I missed something:
+
+	my $string = 'This has $foo and $bar';
+	
+	my %Replacements = (
+		foo  => 'Fred',
 		);
-	$text =~ s/\$(\w+)/$user_defs{$1}/g;
-
+		
+	# $string =~ s/\$(\w+)/$Replacements{$1}/g;
+	$string =~ s/\$(\w+)/
+		exists $Replacements{$1} ? $Replacements{$1} : '???'
+		/eg;
+		
+	print $string;
+	
 =head2 What's wrong with always quoting "$vars"?
 
 The problem is that those double-quotes force
-stringification--coercing numbers and references into
-strings--even when you don't want them to be strings.  Think
-of it this way: double-quote expansion is used to produce
-new strings.  If you already have a string, why do you need
-more?
+stringification--coercing numbers and references into strings--even
+when you don't want them to be strings.  Think of it this way:
+double-quote expansion is used to produce new strings.  If you already
+have a string, why do you need more?
 
 If you get used to writing odd things like these:
 
@@ -2074,7 +2105,7 @@ what you want. It handles that extra work.
 =head2 How do I handle binary data correctly?
 
 Perl is binary clean, so it can handle binary data just fine.
-On Windows or DOS, however, you have to use C<binmode> for binary 
+On Windows or DOS, however, you have to use C<binmode> for binary
 files to avoid conversions for line endings. In general, you should
 use C<binmode> any time you want to work with binary data.
 
@@ -2184,9 +2215,9 @@ the C<PDL> module from CPAN instead--it makes number-crunching easy.
 
 =head1 REVISION
 
-Revision: $Revision: 6816 $
+Revision: $Revision: 7954 $
 
-Date: $Date: 2006-08-20 21:20:03 +0200 (dim, 20 aoû 2006) $
+Date: $Date: 2006-10-16 22:07:58 +0200 (lun, 16 oct 2006) $
 
 See L<perlfaq> for source control details and availability.
 
diff --git a/pod/perlfaq5.pod b/pod/perlfaq5.pod
index b4d3e7553e..d171522e1a 100644
--- a/pod/perlfaq5.pod
+++ b/pod/perlfaq5.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq5 - Files and Formats ($Revision: 6019 $)
+perlfaq5 - Files and Formats ($Revision: 7875 $)
 
 =head1 DESCRIPTION
 
@@ -55,11 +55,162 @@ or IO::Socket:
 
 	$sock->autoflush();
 
-=head2 How do I change one line in a file/delete a line in a file/insert a line in the middle of a file/append to the beginning of a file?
+=head2 How do I change, delete, or insert a line in a file, or append to the beginning of a file?
 X<file, editing>
 
-Use the Tie::File module, which is included in the standard
-distribution since Perl 5.8.0.
+(contributed by brian d foy)
+
+The basic idea of inserting, changing, or deleting a line from a text
+file involves reading and printing the file to the point you want to
+make the change, making the change, then reading and printing the rest
+of the file. Perl doesn't provide random access to lines (especially
+since the record input separator, C<$/>, is mutable), although modules
+such as C<Tie::File> can fake it.
+
+A Perl program to do these tasks takes the basic form of opening a
+file, printing its lines, then closing the file:
+
+	open my $in,  '<',  $file      or die "Can't read old file: $!";
+	open my $out, '>', "$file.new" or die "Can't write new file: $!";
+
+	while( <$in> )
+		{
+		print $out $_;
+		}
+
+   close $out;
+
+Within that basic form, add the parts that you need to insert, change,
+or delete lines.
+
+To prepend lines to the beginning, print those lines before you enter
+the loop that prints the existing lines.
+
+	open my $in,  '<',  $file      or die "Can't read old file: $!";
+	open my $out, '>', "$file.new" or die "Can't write new file: $!";
+
+	print "# Add this line to the top\n"; # <--- HERE'S THE MAGIC
+
+	while( <$in> )
+		{
+		print $out $_;
+		}
+
+   close $out;
+
+To change existing lines, insert the code to modify the lines inside
+the C<while> loop. In this case, the code finds all lowercased
+versions of "perl" and uppercases them. The happens for every line, so
+be sure that you're supposed to do that on every line!
+
+	open my $in,  '<',  $file      or die "Can't read old file: $!";
+	open my $out, '>', "$file.new" or die "Can't write new file: $!";
+
+	print "# Add this line to the top\n";
+
+	while( <$in> )
+		{
+		s/\b(perl)\b/Perl/g;
+		print $out $_;
+		}
+
+   close $out;
+
+To change only a particular line, the input line number, C<$.>, is
+useful. Use C<next> to skip all lines up to line 5, make a change and
+print the result, then stop further processing with C<last>.
+
+	while( <$in> )
+		{
+		next unless $. == 5;
+		s/\b(perl)\b/Perl/g;
+		print $out $_;
+		last;
+		}
+
+To skip lines, use the looping controls. The C<next> in this example
+skips comment lines, and the C<last> stops all processing once it
+encounters either C<__END__> or C<__DATA__>.
+
+	while( <$in> )
+		{
+		next if /^\s+#/;             # skip comment lines
+		last if /^__(END|DATA)__$/;  # stop at end of code marker
+		print $out $_;
+		}
+
+Do the same sort of thing to delete a particular line by using C<next>
+to skip the lines you don't want to show up in the output. This
+example skips every fifth line:
+
+	while( <$in> )
+		{
+		next unless $. % 5;
+		print $out $_;
+		}
+
+If, for some odd reason, you really want to see the whole file at once
+rather than processing line by line, you can slurp it in (as long as
+you can fit the whole thing in memory!):
+
+	open my $in,  '<',  $file      or die "Can't read old file: $!"
+	open my $out, '>', "$file.new" or die "Can't write new file: $!";
+
+	my @lines = do { local $/; <$in> }; # slurp!
+
+		# do your magic here
+
+	print $out @lines;
+
+Modules such as C<File::Slurp> and C<Tie::File> can help with that
+too. If you can, however, avoid reading the entire file at once. Perl
+won't give that memory back to the operating system until the process
+finishes.
+
+You can also use Perl one-liners to modify a file in-place. The
+following changes all 'Fred' to 'Barney' in F<inFile.txt>, overwriting
+the file with the new contents. With the C<-p> switch, Perl wraps a
+C<while> loop around the code you specify with C<-e>, and C<-i> turns
+on in-place editing. The current line is in C<$_>. With C<-p>, Perl
+automatically prints the value of C<$_> at the end of the loop. See
+L<perlrun> for more details.
+
+	perl -pi -e 's/Fred/Barney/' inFile.txt
+
+To make a backup of C<inFile.txt>, give C<-i> a file extension to add:
+
+	perl -pi.bak -e 's/Fred/Barney/' inFile.txt
+
+To change only the fifth line, you can add a test checking C<$.>, the
+input line number, then only perform the operation when the test
+passes:
+
+	perl -pi -e 's/Fred/Barney/ if $. == 5' inFile.txt
+
+To add lines before a certain line, you can add a line (or lines!)
+before Perl prints C<$_>:
+
+	perl -pi -e 'print "Put before third line\n" if $. == 3' inFile.txt
+
+You can even add a line to the beginning of a file, since the current
+line prints at the end of the loop:
+
+	perl -pi -e 'print "Put before first line\n" if $. == 1' inFile.txt
+
+To insert a line after one already in the file, use the C<-n> switch.
+It's just like C<-p> except that it doesn't print C<$_> at the end of
+the loop, so you have to do that yourself. In this case, print C<$_>
+first, then print the line that you want to add.
+
+	perl -ni -e 'print; print "Put after fifth line\n" if $. == 5' inFile.txt
+
+To delete lines, only print the ones that you want.
+
+	perl -ni -e 'print unless /d/' inFile.txt
+
+		... or ...
+
+	perl -pi -e 'next unless /d/' inFile.txt
 
 =head2 How do I count the number of lines in a file?
 X<file, counting lines> X<lines> X<line>
@@ -237,7 +388,6 @@ the filehandle reference is a simple scalar.
 		print {$fhs[$i]} "just another Perl answer, \n";
 		}
 
-
 Before perl5.6, you had to deal with various typeglob idioms
 which you may see in older code.
 
@@ -1115,9 +1265,9 @@ If your array contains lines, just print them:
 
 =head1 REVISION
 
-Revision: $Revision: 6019 $
+Revision: $Revision: 7875 $
 
-Date: $Date: 2006-05-04 19:04:31 +0200 (jeu, 04 mai 2006) $
+Date: $Date: 2006-10-04 22:39:26 +0200 (mer, 04 oct 2006) $
 
 See L<perlfaq> for source control details and availability.
 
diff --git a/pod/perlfaq6.pod b/pod/perlfaq6.pod
index 8fe9c2e4c5..ab19de8cfa 100644
--- a/pod/perlfaq6.pod
+++ b/pod/perlfaq6.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq6 - Regular Expressions ($Revision: 6479 $)
+perlfaq6 - Regular Expressions ($Revision: 7910 $)
 
 =head1 DESCRIPTION
 
@@ -143,10 +143,10 @@ Here's another example of using C<..>:
 
 	while (<>) {
 		$in_header =   1  .. /^$/;
-		$in_body   = /^$/ .. eof();
+		$in_body   = /^$/ .. eof;
 	# now choose between them
 	} continue {
-		reset if eof();		# fix $.
+		$. = 0 if eof;	# fix $.
 	}
 
 =head2 I put a regular expression into $/ but it didn't work. What's wrong?
@@ -422,7 +422,8 @@ whitespace and comments.  Here it is expanded, courtesy of Fred Curtis.
        )
      }{defined $2 ? $2 : ""}gxse;
 
-A slight modification also removes C++ comments:
+A slight modification also removes C++ comments, as long as they are not
+spread over multiple lines using a continuation character):
 
 	s#/\*[^*]*\*+([^/*][^*]*\*+)*/|//[^\n]*|("(\\.|[^"\\])*"|'(\\.|[^'\\])*'|.[^/"'\\]*)#defined $2 ? $2 : ""#gse;
 
@@ -952,9 +953,9 @@ Or...
 
 =head1 REVISION
 
-Revision: $Revision: 6479 $
+Revision: $Revision: 7910 $
 
-Date: $Date: 2006-06-07 09:48:12 +0200 (mer, 07 jun 2006) $
+Date: $Date: 2006-10-07 22:38:54 +0200 (sam, 07 oct 2006) $
 
 See L<perlfaq> for source control details and availability.
 
diff --git a/pod/perlfaq7.pod b/pod/perlfaq7.pod
index d8fc183e2f..65ff7a70c5 100644
--- a/pod/perlfaq7.pod
+++ b/pod/perlfaq7.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq7 - General Perl Language Issues ($Revision: 6833 $)
+perlfaq7 - General Perl Language Issues ($Revision: 7875 $)
 
 =head1 DESCRIPTION
 
@@ -634,8 +634,8 @@ where they don't belong.
 This is explained in more depth in the L<perlsyn>.  Briefly, there's
 no official case statement, because of the variety of tests possible
 in Perl (numeric comparison, string comparison, glob comparison,
-regex matching, overloaded comparisons, ...).  Larry couldn't decide 
-how best to do this, so he left it out, even though it's been on the 
+regex matching, overloaded comparisons, ...).  Larry couldn't decide
+how best to do this, so he left it out, even though it's been on the
 wish list since perl1.
 
 Starting from Perl 5.8 to get switch and case one can use the
@@ -962,9 +962,9 @@ where you expect it so you need to adjust your shebang line.
 
 =head1 REVISION
 
-Revision: $Revision: 6833 $
+Revision: $Revision: 7875 $
 
-Date: $Date: 2006-09-02 21:16:20 +0200 (sam, 02 sep 2006) $
+Date: $Date: 2006-10-04 22:39:26 +0200 (mer, 04 oct 2006) $
 
 See L<perlfaq> for source control details and availability.
 
diff --git a/pod/perlfaq9.pod b/pod/perlfaq9.pod
index 8faf2fb003..0a2ef460b6 100644
--- a/pod/perlfaq9.pod
+++ b/pod/perlfaq9.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-perlfaq9 - Networking ($Revision: 6309 $)
+perlfaq9 - Networking ($Revision: 7875 $)
 
 =head1 DESCRIPTION
 
@@ -186,11 +186,29 @@ method.
 See the section in the CGI.pm documentation on file uploads for code
 examples and details.
 
-=head2 How do I make a pop-up menu in HTML?
+=head2 How do I make an HTML pop-up menu with Perl?
+
+(contributed by brian d foy)
+
+The CGI.pm module (which comes with Perl) has functions to create
+the HTML form widgets. See the CGI.pm documentation for more
+examples.
+
+	use CGI qw/:standard/;
+	print header,
+		start_html('Favorite Animals'),
+
+		start_form,
+			"What's your favorite animal? ",
+        popup_menu(
+        	-name   => 'animal',
+			-values => [ qw( Llama Alpaca Camel Ram ) ]
+			),
+        submit,
+
+ 		end_form,
+        end_html;
 
-Use the B<< <SELECT> >> and B<< <OPTION> >> tags.  The CGI.pm
-module (available from CPAN) supports this widget, as well as many
-others, including some that it cleverly synthesizes on its own.
 
 =head2 How do I fetch an HTML file?
 
@@ -649,9 +667,9 @@ http://search.cpan.org/search?query=RPC&mode=all ).
 
 =head1 REVISION
 
-Revision: $Revision: 6309 $
+Revision: $Revision: 7875 $
 
-Date: $Date: 2006-05-18 07:44:45 +0200 (jeu, 18 mai 2006) $
+Date: $Date: 2006-10-04 22:39:26 +0200 (mer, 04 oct 2006) $
 
 See L<perlfaq> for source control details and availability.