[win32] merge changes#872,873 from maintbranch

p4raw-link: @873 on //depot/maint-5.004/perl: 990f469d529b62458be38e8659885fd26d353629
p4raw-link: @872 on //depot/maint-5.004/perl: 0b85608df162729d39cb0f96c9f88c7de0a3ceab

p4raw-id: //depot/win32/perl@935

1 files changed, 55 insertions, 10 deletions

diff --git a/utils/perldoc.PL b/utils/perldoc.PL
index 752f335ca2..bb3d69d8f5 100644
--- a/utils/perldoc.PL
+++ b/utils/perldoc.PL
@@ -50,6 +50,7 @@ if(@ARGV<1) {
 	die <<EOF;
 Usage: $me [-h] [-v] [-t] [-u] [-m] [-l] [-F] [-X] PageName|ModuleName|ProgramName
        $me -f PerlFunc
+       $me -q FAQKeywords
 
 The -h option prints more help.  Also try "perldoc perldoc" to get
 aquainted with the system.
@@ -73,18 +74,20 @@ sub usage{
     die <<EOF;
 perldoc [options] PageName|ModuleName|ProgramName...
 perldoc [options] -f BuiltinFunction
+perldoc [options] -q FAQRegex
 
 Options:
     -h   Display this help message
     -t   Display pod using pod2text instead of pod2man and nroff
              (-t is the default on win32)
     -u	 Display unformatted pod text
-    -m   Display modules file in its entirety
-    -l   Display the modules file name
+    -m   Display module's file in its entirety
+    -l   Display the module's file name
     -F   Arguments are file names, not modules
     -v	 Verbosely describe what's going on
     -X	 use index if present (looks for pod.idx at $Config{archlib})
 
+
 PageName|ModuleName...
          is the name of a piece of documentation that you want to look at. You 
          may either give a descriptive name of the page (as in the case of
@@ -95,7 +98,11 @@ PageName|ModuleName...
 BuiltinFunction
          is the name of a perl function.  Will extract documentation from
          `perlfunc'.
-         
+
+FAQRegex
+         is a regex. Will search perlfaq[1-9] for and extract any
+         questions that match.
+
 Any switches in the PERLDOC environment variable will be used before the 
 command line arguments.  The optional pod index file contains a list of
 filenames, one per line.
@@ -108,7 +115,7 @@ use Text::ParseWords;
 
 unshift(@ARGV,shellwords($ENV{"PERLDOC"}));
 
-getopts("mhtluvFf:X") || usage;
+getopts("mhtluvFf:Xq:") || usage;
 
 usage if $opt_h || $opt_h; # avoid -w warning
 
@@ -125,6 +132,8 @@ if ($opt_t) { require Pod::Text; import Pod::Text; }
 
 if ($opt_f) {
    @pages = ("perlfunc");
+} elsif ($opt_q) {
+   @pages = ("perlfaq1" .. "perlfaq9");
 } else {
    @pages = @ARGV;
 }
@@ -206,11 +215,11 @@ sub minus_f_nocase {
 
 sub check_file {
     my($file) = @_;
-    if ($opt_m) {
-	return minus_f_nocase($file) ? $file : "";
-    } else {
-	return minus_f_nocase($file) && containspod($file) ? $file : "";
-    }
+    $file = minus_f_nocase($file);
+	return "" unless $file;
+	return $file if $::opt_m;
+    return $file if containspod($file);
+    return "";
 }
 
 
@@ -415,6 +424,39 @@ if ($opt_f) {
    exit;
 }
 
+if ($opt_q) {
+   local @ARGV = @found;	# I'm lazy, sue me.
+   my $found = 0;
+   my %found_in;
+   my @pod;
+
+   while (<>) {
+      if (/^=head2\s+.*$opt_q/oi) {
+	 $found = 1;
+	 push @pod, "=head1 Found in $ARGV\n\n" unless $found_in{$ARGV}++;
+      } elsif (/^=head2/) {
+	 $found = 0;
+      }
+      next unless $found;
+      push @pod, $_;
+   }
+   
+   if (@pod) {
+      if ($opt_t) {
+	 open(FORMATTER, "| pod2text") || die "Can't start filter";
+	 print FORMATTER "=over 8\n\n";
+	 print FORMATTER @pod;
+	 print FORMATTER "=back\n";
+	 close(FORMATTER);
+      } else {
+	 print @pod;
+      }
+   } else {
+      die "No documentation for perl function `$opt_f' found\n";
+   }
+   exit;
+}
+
 foreach (@found) {
 
 	if($opt_t) {
@@ -548,7 +590,10 @@ command line arguments.  C<perldoc> also searches directories
 specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
 defined) and C<PATH> environment variables.
 (The latter is so that embedded pods for executables, such as
-C<perldoc> itself, are available.)
+C<perldoc> itself, are available.)  C<perldoc> will use, in order of
+preference, the pager defined in C<PERLDOC_PAGER>, C<MANPAGER>, or
+C<PAGER> before trying to find a pager on its own.  (C<MANPAGER> is not
+used if C<perldoc> was told to display plain text or unformatted pod.)
 
 =head1 AUTHOR