Update Pod-Perldoc to CPAN version 3.21

  [DELTA]

3.21 - Mon Jan  6 02:17:07 UTC 2014
    * Add '-a' flag to search through perlapi
      documentation. Patch by Matthew Horsfall.
    * Apply RT #91733 to install perldoc.pod in the
      right place. Should fix RT #88898 too. Patch
      by Dave Mitchell.

3.21_01 - Tue Nov 19 17:07:46 UTC 2013
    * Do not modify @INC to look for docs perl RT #120357
      (Patch by Kent Fredric)
    * Prefer mandoc on bitrig
    * Fix typos

14 files changed, 125 insertions, 27 deletions

diff --git a/cpan/Pod-Perldoc/lib/Pod/Perldoc.pm b/cpan/Pod-Perldoc/lib/Pod/Perldoc.pm
index 9cdee805f7..363626fb77 100644
--- a/cpan/Pod-Perldoc/lib/Pod/Perldoc.pm
+++ b/cpan/Pod-Perldoc/lib/Pod/Perldoc.pm
@@ -12,7 +12,7 @@ use File::Spec::Functions qw(catfile catdir splitdir);
 use vars qw($VERSION @Pagers $Bindir $Pod2man
   $Temp_Files_Created $Temp_File_Lifetime
 );
-$VERSION = '3.20';
+$VERSION = '3.21';
 
 #..........................................................................
 
@@ -90,12 +90,13 @@ $Pod2man = "pod2man" . ( $Config{'versiononly'} ? $Config{'version'} : '' );
 #
 # Option accessors...
 
-foreach my $subname (map "opt_$_", split '', q{mhlDriFfXqnTdULv}) {
+foreach my $subname (map "opt_$_", split '', q{mhlDriFfXqnTdULva}) {
   no strict 'refs';
   *$subname = do{ use strict 'refs';  sub () { shift->_elem($subname, @_) } };
 }
 
 # And these are so that GetOptsOO knows they take options:
+sub opt_a_with { shift->_elem('opt_a', @_) }
 sub opt_f_with { shift->_elem('opt_f', @_) }
 sub opt_q_with { shift->_elem('opt_q', @_) }
 sub opt_d_with { shift->_elem('opt_d', @_) }
@@ -293,6 +294,7 @@ Options:
     -X   Use index if present (looks for pod.idx at $Config{archlib})
     -q   Search the text of questions (not answers) in perlfaq[1-9]
     -f   Search Perl built-in functions
+    -a   Search Perl API
     -v   Search predefined Perl variables
 
 PageName|ModuleName|ProgramName|URL...
@@ -399,6 +401,7 @@ Examples:
     $program_name -f PerlFunc
     $program_name -q FAQKeywords
     $program_name -v PerlVar
+    $program_name -a PerlAPI
 
 The -h option prints more help.  Also try "$program_name perldoc" to get
 acquainted with the system.                        [Perldoc v$VERSION]
@@ -441,6 +444,7 @@ sub init {
   $self->{'pagers' } = [@Pagers] unless exists $self->{'pagers'};
   $self->{'bindir' } = $Bindir   unless exists $self->{'bindir'};
   $self->{'pod2man'} = $Pod2man  unless exists $self->{'pod2man'};
+  $self->{'search_path'} = [ ]   unless exists $self->{'search_path'};
 
   push @{ $self->{'formatter_switches'} = [] }, (
    # Yeah, we could use a hashref, but maybe there's some class where options
@@ -519,6 +523,7 @@ sub process {
     if(    $self->opt_f) { @pages = qw(perlfunc perlop)        }
     elsif( $self->opt_q) { @pages = ("perlfaq1" .. "perlfaq9") }
     elsif( $self->opt_v) { @pages = ("perlvar")                }
+    elsif( $self->opt_a) { @pages = ("perlapi")                }
     else                 { @pages = @{$self->{'args'}};
                            # @pages = __FILE__
                            #  if @pages == 1 and $pages[0] eq 'perldoc';
@@ -529,7 +534,7 @@ sub process {
     $self->find_good_formatter_class();
     $self->formatter_sanity_check();
 
-    $self->maybe_diddle_INC();
+    $self->maybe_extend_searchpath();
       # for when we're apparently in a module or extension directory
 
     my @found = $self->grand_search_init(\@pages);
@@ -596,7 +601,7 @@ sub find_good_formatter_class {
       } else {
         $^W = 0;
         # The average user just has no reason to be seeing
-        #  $^W-suppressible warnings from the the require!
+        #  $^W-suppressible warnings from the require!
       }
 
       eval "require $c";
@@ -795,8 +800,12 @@ sub options_sanity {
     # Any sanity-checking need doing here?
 
     # But does not make sense to set either -f or -q in $ENV{"PERLDOC"}
-    if( $self->opt_f or $self->opt_q ) {
-    $self->usage("Only one of -f -or -q") if $self->opt_f and $self->opt_q;
+    if( $self->opt_f or $self->opt_q or $self->opt_a) {
+    my $count;
+    $count++ if $self->opt_f;
+    $count++ if $self->opt_q;
+    $count++ if $self->opt_a;
+    $self->usage("Only one of -f or -q or -a") if $count > 1;
     $self->warn(
         "Perldoc is meant for reading one file at a time.\n",
         "So these parameters are being ignored: ",
@@ -858,7 +867,7 @@ sub grand_search_init {
 
         # We must look both in @INC for library modules and in $bindir
         # for executables, like h2xs or perldoc itself.
-        push @searchdirs, ($self->{'bindir'}, @INC);
+        push @searchdirs, ($self->{'bindir'}, @{$self->{search_path}}, @INC);
         unless ($self->opt_m) {
             if ($self->is_vms) {
                 my($i,$trn);
@@ -916,13 +925,15 @@ sub maybe_generate_dynamic_pod {
     my($self, $found_things) = @_;
     my @dynamic_pod;
 
+    $self->search_perlapi($found_things, \@dynamic_pod)   if  $self->opt_a;
+
     $self->search_perlfunc($found_things, \@dynamic_pod)  if  $self->opt_f;
 
     $self->search_perlvar($found_things, \@dynamic_pod)   if  $self->opt_v;
 
     $self->search_perlfaqs($found_things, \@dynamic_pod)  if  $self->opt_q;
 
-    if( ! $self->opt_f and ! $self->opt_q and ! $self->opt_v ) {
+    if( ! $self->opt_f and ! $self->opt_q and ! $self->opt_v and ! $self->opt_a) {
         DEBUG > 4 and print "That's a non-dynamic pod search.\n";
     } elsif ( @dynamic_pod ) {
         $self->aside("Hm, I found some Pod from that search!\n");
@@ -935,7 +946,7 @@ sub maybe_generate_dynamic_pod {
         push @{ $self->{'temp_file_list'} }, $buffer;
          # I.e., it MIGHT be deleted at the end.
 
-        my $in_list = !$self->not_dynamic && $self->opt_f || $self->opt_v;
+        my $in_list = !$self->not_dynamic && $self->opt_f || $self->opt_v || $self->opt_a;
 
         print $buffd "=over 8\n\n" if $in_list;
         print $buffd @dynamic_pod  or $self->die( "Can't print $buffer: $!" );
@@ -1144,6 +1155,83 @@ sub search_perlop {
 
 #..........................................................................
 
+sub search_perlapi {
+    my($self, $found_things, $pod) = @_;
+
+    DEBUG > 2 and print "Search: @$found_things\n";
+
+    my $perlapi = shift @$found_things;
+    open(PAPI, "<", $perlapi)               # "Funk is its own reward"
+        or $self->die("Can't open $perlapi: $!");
+
+    my $search_re = quotemeta($self->opt_a);
+
+    DEBUG > 2 and
+     print "Going to perlapi-scan for $search_re in $perlapi\n";
+
+    # Check available translator or backup to default (english)
+    if ( $self->opt_L && defined $self->{'translators'}->[0] ) {
+        my $tr = $self->{'translators'}->[0];
+        if ( $] < 5.008 ) {
+            $self->aside("Your old perl doesn't really have proper unicode support.");
+        }
+        else {
+            binmode(PAPI, ":utf8");
+        }
+    }
+
+    local $_;
+
+    # Look for our function
+    my $found = 0;
+    my $inlist = 0;
+
+    my @related;
+    my $related_re;
+    while (<PAPI>) {  # "The Mothership Connection is here!"
+        if ( m/^=item\s+$search_re\b/ )  {
+            $found = 1;
+        }
+        elsif (@related > 1 and /^=item/) {
+            $related_re ||= join "|", @related;
+            if (m/^=item\s+(?:$related_re)\b/) {
+                $found = 1;
+            }
+            else {
+                last;
+            }
+        }
+        elsif (/^=item/) {
+            last if $found > 1 and not $inlist;
+        }
+        elsif ($found and /^X<[^>]+>/) {
+            push @related, m/X<([^>]+)>/g;
+        }
+        next unless $found;
+        if (/^=over/) {
+            ++$inlist;
+        }
+        elsif (/^=back/) {
+            last if $found > 1 and not $inlist;
+            --$inlist;
+        }
+        push @$pod, $_;
+        ++$found if /^\w/;        # found descriptive text
+    }
+
+    if (!@$pod) {
+        CORE::die( sprintf
+          "No documentation for perl api function '%s' found\n",
+          $self->opt_a )
+        ;
+    }
+    close PAPI                or $self->die( "Can't open $perlapi: $!" );
+
+    return;
+}
+
+#..........................................................................
+
 sub search_perlfunc {
     my($self, $found_things, $pod) = @_;
 
@@ -1648,19 +1736,18 @@ sub containspod {
 
 #..........................................................................
 
-sub maybe_diddle_INC {
+sub maybe_extend_searchpath {
   my $self = shift;
 
   # Does this look like a module or extension directory?
 
   if (-f "Makefile.PL" || -f "Build.PL") {
 
-    # Add "." and "lib" to @INC (if they exist)
-    eval q{ use lib qw(. lib); 1; } or $self->die;
+    push @{$self->{search_path} }, '.','lib';
 
     # don't add if superuser
     if ($< && $> && -d "blib") {   # don't be looking too hard now!
-      eval q{ use blib; 1 };
+      push @{ $self->{search_path} }, 'blib';
       $self->warn( $@ ) if $@ && $self->opt_D;
     }
   }
diff --git a/cpan/Pod-Perldoc/lib/Pod/Perldoc/BaseTo.pm b/cpan/Pod-Perldoc/lib/Pod/Perldoc/BaseTo.pm
index 80ffc800df..10eb10de5b 100644
--- a/cpan/Pod-Perldoc/lib/Pod/Perldoc/BaseTo.pm
+++ b/cpan/Pod-Perldoc/lib/Pod/Perldoc/BaseTo.pm
@@ -3,7 +3,7 @@ use strict;
 use warnings;
 
 use vars qw($VERSION);
-$VERSION = '3.20';
+$VERSION = '3.21';
 
 use Carp                  qw(croak carp);
 use Config                qw(%Config);
@@ -33,6 +33,7 @@ BEGIN {
  *is_linux   = $^O eq 'linux'    ? \&TRUE : \&FALSE unless defined &is_linux;
  *is_hpux    = $^O =~ m/hpux/    ? \&TRUE : \&FALSE unless defined &is_hpux;
  *is_openbsd = $^O =~ m/openbsd/ ? \&TRUE : \&FALSE unless defined &is_openbsd;
+ *is_bitrig = $^O =~ m/bitrig/ ? \&TRUE : \&FALSE unless defined &is_bitrig;
 }
 
 sub _perldoc_elem {
diff --git a/cpan/Pod-Perldoc/lib/Pod/Perldoc/GetOptsOO.pm b/cpan/Pod-Perldoc/lib/Pod/Perldoc/GetOptsOO.pm
index 5b90794fc1..07e9b17041 100644
--- a/cpan/Pod-Perldoc/lib/Pod/Perldoc/GetOptsOO.pm
+++ b/cpan/Pod-Perldoc/lib/Pod/Perldoc/GetOptsOO.pm
@@ -2,7 +2,7 @@ package Pod::Perldoc::GetOptsOO;
 use strict;
 
 use vars qw($VERSION);
-$VERSION = '3.20';
+$VERSION = '3.21';
 
 BEGIN { # Make a DEBUG constant ASAP
   *DEBUG = defined( &Pod::Perldoc::DEBUG )
diff --git a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToANSI.pm b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToANSI.pm
index baaea039e0..263056c0b0 100644
--- a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToANSI.pm
+++ b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToANSI.pm
@@ -4,7 +4,7 @@ use warnings;
 use parent qw(Pod::Perldoc::BaseTo);
 
 use vars qw($VERSION);
-$VERSION = '3.20';
+$VERSION = '3.21';
 
 sub is_pageable        { 1 }
 sub write_with_binmode { 0 }
diff --git a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToChecker.pm b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToChecker.pm
index 6bf0cf8c9d..43e136ea8e 100644
--- a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToChecker.pm
+++ b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToChecker.pm
@@ -4,7 +4,7 @@ use warnings;
 use vars qw(@ISA);
 
 use vars qw($VERSION);
-$VERSION = '3.20';
+$VERSION = '3.21';
 
 # Pick our superclass...
 #
diff --git a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToMan.pm b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToMan.pm
index bdd014025f..42d3f01efc 100644
--- a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToMan.pm
+++ b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToMan.pm
@@ -5,7 +5,7 @@ use warnings;
 use parent qw(Pod::Perldoc::BaseTo);
 
 use vars qw($VERSION);
-$VERSION = '3.20';
+$VERSION = '3.21';
 
 use File::Spec::Functions qw(catfile);
 use Pod::Man 2.18;
@@ -63,7 +63,7 @@ sub init {
 sub _roffer_candidates {
 	my( $self ) = @_;
 
-	if( $self->is_openbsd ) { qw( mandoc groff nroff ) }
+	if( $self->is_openbsd || $self->is_bitrig ) { qw( mandoc groff nroff ) }
 	else                    { qw( groff nroff mandoc ) }
 	}
 
@@ -314,7 +314,7 @@ sub _filter_through_nroff {
         # Eliminate whitespace 
         $switches =~ s/\s//g;
 
-        # Then seperate the switches with a zero-width positive 
+        # Then separate the switches with a zero-width positive 
         # lookahead on the dash.
         #
         # See:
diff --git a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToNroff.pm b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToNroff.pm
index c9fa0fabdc..74f54cdf1c 100644
--- a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToNroff.pm
+++ b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToNroff.pm
@@ -4,7 +4,7 @@ use warnings;
 use parent qw(Pod::Perldoc::BaseTo);
 
 use vars qw($VERSION);
-$VERSION = '3.20';
+$VERSION = '3.21';
 
 # This is unlike ToMan.pm in that it emits the raw nroff source!
 
diff --git a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToPod.pm b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToPod.pm
index dc5523f4da..aeff83a580 100644
--- a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToPod.pm
+++ b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToPod.pm
@@ -4,7 +4,7 @@ use warnings;
 use parent qw(Pod::Perldoc::BaseTo);
 
 use vars qw($VERSION);
-$VERSION = '3.20';
+$VERSION = '3.21';
 
 sub is_pageable        { 1 }
 sub write_with_binmode { 0 }
diff --git a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToRtf.pm b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToRtf.pm
index 75ea630f1d..11a709449f 100644
--- a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToRtf.pm
+++ b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToRtf.pm
@@ -4,7 +4,7 @@ use warnings;
 use parent qw( Pod::Simple::RTF );
 
 use vars qw($VERSION);
-$VERSION = '3.20';
+$VERSION = '3.21';
 
 sub is_pageable        { 0 }
 sub write_with_binmode { 0 }
diff --git a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToTerm.pm b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToTerm.pm
index bdc5625028..4ca61b6a4d 100644
--- a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToTerm.pm
+++ b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToTerm.pm
@@ -3,7 +3,7 @@ use strict;
 use warnings;
 
 use vars qw($VERSION);
-$VERSION = '3.20';
+$VERSION = '3.21';
 
 use parent qw(Pod::Perldoc::BaseTo);
 
diff --git a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToText.pm b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToText.pm
index b2861f3020..5b024dd696 100644
--- a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToText.pm
+++ b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToText.pm
@@ -3,7 +3,7 @@ use strict;
 use warnings;
 
 use vars qw($VERSION);
-$VERSION = '3.20';
+$VERSION = '3.21';
 
 use parent qw(Pod::Perldoc::BaseTo);
 
diff --git a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToTk.pm b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToTk.pm
index 8c1240ac14..37b0d3f4ae 100644
--- a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToTk.pm
+++ b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToTk.pm
@@ -3,7 +3,7 @@ use strict;
 use warnings;
 
 use vars qw($VERSION);
-$VERSION = '3.20';
+$VERSION = '3.21';
 
 use parent qw(Pod::Perldoc::BaseTo);
 
diff --git a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToXml.pm b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToXml.pm
index 9de73fba0b..0c03614d1e 100644
--- a/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToXml.pm
+++ b/cpan/Pod-Perldoc/lib/Pod/Perldoc/ToXml.pm
@@ -6,7 +6,7 @@ use vars qw($VERSION);
 use parent qw( Pod::Simple::XMLOutStream );
 
 use vars qw($VERSION);
-$VERSION = '3.20';
+$VERSION = '3.21';
 
 sub is_pageable        { 0 }
 sub write_with_binmode { 0 }
diff --git a/cpan/Pod-Perldoc/perldoc.pod b/cpan/Pod-Perldoc/perldoc.pod
index 55febc4bf9..a626044ef6 100644
--- a/cpan/Pod-Perldoc/perldoc.pod
+++ b/cpan/Pod-Perldoc/perldoc.pod
@@ -28,6 +28,8 @@ Examples:
 
     perldoc -v PerlVariable
 
+    perldoc -a PerlAPI
+
 See below for more description of the switches.
 
 =head1 DESCRIPTION
@@ -100,6 +102,14 @@ Example:
 
      perldoc -q shuffle
 
+=item B<-a> I<perlapifunc>
+
+The B<-a> option followed by the name of a perl api function will
+extract the documentation of this function from L<perlapi>.
+
+Example:
+
+     perldoc -a newHV
 
 =item B<-v> I<perlvar>