update Pod-Perldoc to version 3.14_07

From: "Adriano Ferreira" <aferreira@shopzilla.com>
Message-ID: <73ddeb6c0806080729n63fc806dq83287e57347a4b5f@mail.gmail.com>

p4raw-id: //depot/perl@34028

11 files changed, 264 insertions, 20 deletions

diff --git a/lib/Pod/Perldoc.pm b/lib/Pod/Perldoc.pm
index 9ed66e8091..5569d9f041 100644
--- a/lib/Pod/Perldoc.pm
+++ b/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.14_04';
+$VERSION = '3.14_07';
 #..........................................................................
 
 BEGIN {  # Make a DEBUG constant very first thing...
@@ -32,6 +32,7 @@ use Pod::Perldoc::GetOptsOO; # uses the DEBUG.
 
 sub TRUE  () {1}
 sub FALSE () {return}
+sub BE_LENIENT () {1}
 
 BEGIN {
  *IS_VMS     = $^O eq 'VMS'     ? \&TRUE : \&FALSE unless defined &IS_VMS;
@@ -62,7 +63,7 @@ $Pod2man = "pod2man" . ( $Config{'versiononly'} ? $Config{'version'} : '' );
 #
 # Option accessors...
 
-foreach my $subname (map "opt_$_", split '', q{mhlvriFfXqnTdUL}) {
+foreach my $subname (map "opt_$_", split '', q{mhlDriFfXqnTdULv}) {
   no strict 'refs';
   *$subname = do{ use strict 'refs';  sub () { shift->_elem($subname, @_) } };
 }
@@ -72,6 +73,7 @@ sub opt_f_with { shift->_elem('opt_f', @_) }
 sub opt_q_with { shift->_elem('opt_q', @_) }
 sub opt_d_with { shift->_elem('opt_d', @_) }
 sub opt_L_with { shift->_elem('opt_L', @_) }
+sub opt_v_with { shift->_elem('opt_v', @_) }
 
 sub opt_w_with { # Specify an option for the formatter subclass
   my($self, $value) = @_;
@@ -209,9 +211,9 @@ sub new {  # yeah, nothing fancy
 
 #..........................................................................
 
-sub aside {  # If we're in -v or DEBUG mode, say this.
+sub aside {  # If we're in -D or DEBUG mode, say this.
   my $self = shift;
-  if( DEBUG or $self->opt_v ) {
+  if( DEBUG or $self->opt_D ) {
     my $out = join( '',
       DEBUG ? do {
         my $callsub = (caller(1))[3];
@@ -240,6 +242,7 @@ sub usage {
 perldoc [options] PageName|ModuleName|ProgramName...
 perldoc [options] -f BuiltinFunction
 perldoc [options] -q FAQRegex
+perldoc [options] -v PerlVariable
 
 Options:
     -h   Display this help message
@@ -253,7 +256,7 @@ Options:
     -n   Specify replacement for nroff
     -l   Display the module's file name
     -F   Arguments are file names, not modules
-    -v   Verbosely describe what's going on
+    -D   Verbosely describe what's going on
     -T   Send output to STDOUT without any pager
     -d output_filename_to_send_to
     -o output_format_name
@@ -262,6 +265,8 @@ Options:
     -L translation_code   Choose doc translation (if any)
     -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
+    -v   Search predefined Perl variables
 
 PageName|ModuleName...
          is the name of a piece of documentation that you want to look at. You
@@ -293,9 +298,10 @@ sub usage_brief {
   $me =~ s,.*[/\\],,; # get basename
   
   die <<"EOUSAGE";
-Usage: $me [-h] [-V] [-r] [-i] [-v] [-t] [-u] [-m] [-n nroffer_program] [-l] [-T] [-d output_filename] [-o output_format] [-M FormatterModuleNameToUse] [-w formatter_option:option_value] [-L translation_code] [-F] [-X] PageName|ModuleName|ProgramName
+Usage: $me [-h] [-V] [-r] [-i] [-D] [-t] [-u] [-m] [-n nroffer_program] [-l] [-T] [-d output_filename] [-o output_format] [-M FormatterModuleNameToUse] [-w formatter_option:option_value] [-L translation_code] [-F] [-X] PageName|ModuleName|ProgramName
        $me -f PerlFunc
        $me -q FAQKeywords
+       $me -A PerlVar
 
 The -h option prints more help.  Also try "perldoc perldoc" to get
 acquainted with the system.                        [Perldoc v$VERSION]
@@ -415,6 +421,7 @@ sub process {
     $self->{'pages'} = \@pages;
     if(    $self->opt_f) { @pages = ("perlfunc")               }
     elsif( $self->opt_q) { @pages = ("perlfaq1" .. "perlfaq9") }
+    elsif( $self->opt_v) { @pages = ("perlvar")                }
     else                 { @pages = @{$self->{'args'}};
                            # @pages = __FILE__
                            #  if @pages == 1 and $pages[0] eq 'perldoc';
@@ -487,7 +494,7 @@ sub find_good_formatter_class {
       DEBUG > 4 and print "Trying to eval 'require $c'...\n";
 
       local $^W = $^W;
-      if(DEBUG() or $self->opt_v) {
+      if(DEBUG() or $self->opt_D) {
         # feh, let 'em see it
       } else {
         $^W = 0;
@@ -740,6 +747,10 @@ sub grand_search_init {
         if (@files) {
             $self->aside( "Found as @files\n" );
         }
+        # add "perl" prefix, so "perldoc foo" may find perlfoo.pod
+	elsif (BE_LENIENT and !/\W/ and  @files = $self->searchfor(0, "perl$_", @searchdirs)) {
+            $self->aside( "Loosely found as @files\n" );
+        }
         else {
             # no match, try recursive search
             @searchdirs = grep(!/^\.\z/s,@INC);
@@ -776,10 +787,12 @@ sub maybe_generate_dynamic_pod {
     my @dynamic_pod;
     
     $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 ) {
+    if( ! $self->opt_f and ! $self->opt_q and ! $self->opt_v ) {
         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");
@@ -788,7 +801,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->opt_f;
+	my $in_list = $self->opt_f || $self->opt_v;
 
         print $buffd "=over 8\n\n" if $in_list;
         print $buffd @dynamic_pod  or die "Can't print $buffer: $!";
@@ -862,6 +875,79 @@ sub add_translator { # $self->add_translator($lang);
 
 #..........................................................................
 
+sub search_perlvar {
+    my($self, $found_things, $pod) = @_;
+
+    my $opt = $self->opt_v;
+
+    if ( $opt !~ /^ (?: [\@\%\$]\S+ | [A-Z]\w* ) $/x ) {
+        die "'$opt' does not look like a Perl variable\n";
+    }
+
+    DEBUG > 2 and print "Search: @$found_things\n";
+    
+    my $perlvar = shift @$found_things;
+    open(PVAR, "<", $perlvar)               # "Funk is its own reward"
+        or die("Can't open $perlvar: $!");
+
+    if ( $opt =~ /^\$\d+$/ ) { # handle $1, $2, ..., $9
+      $opt = '$<I<digits>>';
+    }
+    my $search_re = quotemeta($opt);
+
+    DEBUG > 2 and
+     print "Going to perlvar-scan for $search_re in $perlvar\n";
+    
+    # Skip introduction
+    local $_;
+    while (<PVAR>) {
+        last if /^=over 8/;
+    }
+
+    # Look for our variable
+    my $found = 0;
+    my $inheader = 1;
+    my $inlist = 0;
+    while (<PVAR>) {  # "The Mothership Connection is here!"
+        last if /^=head2 Error Indicators/;
+        # \b at the end of $` and friends borks things!
+        if ( m/^=item\s+$search_re\s/ )  {
+            $found = 1;
+        }
+        elsif (/^=item/) {
+            last if $found && !$inheader && !$inlist;
+        }
+        elsif (!/^\s+$/) { # not a blank line
+            if ( $found ) {
+                $inheader = 0; # don't accept more =item (unless inlist)
+	    }
+            else {
+                @$pod = (); # reset
+                $inheader = 1; # start over
+                next;
+            }
+	}
+
+        if (/^=over/) {
+            ++$inlist;
+        }
+        elsif (/^=back/) {
+            --$inlist;
+        }
+        push @$pod, $_;
+#        ++$found if /^\w/;        # found descriptive text
+    }
+    @$pod = () unless $found;
+    if (!@$pod) {
+        die "No documentation for perl variable '$opt' found\n";
+    }
+    close PVAR                or die "Can't open $perlvar: $!";
+
+    return;
+}
+
+#..........................................................................
+
 sub search_perlfunc {
     my($self, $found_things, $pod) = @_;
 
@@ -1023,7 +1109,7 @@ sub render_findings {
   # Now, finally, do the formatting!
   {
     local $^W = $^W;
-    if(DEBUG() or $self->opt_v) {
+    if(DEBUG() or $self->opt_D) {
       # feh, let 'em see it
     } else {
       $^W = 0;
@@ -1438,7 +1524,7 @@ sub containspod {
 
     if ( IS_Cygwin  and  -x $file  and  -f "$file.exe" )
     {
-        warn "Cygwin $file.exe search skipped\n"  if DEBUG or $self->opt_v;
+        warn "Cygwin $file.exe search skipped\n"  if DEBUG or $self->opt_D;
         return 0;
     }
 
@@ -1469,7 +1555,7 @@ sub maybe_diddle_INC {
     # don't add if superuser
     if ($< && $> && -d "blib") {   # don't be looking too hard now!
       eval q{ use blib; 1 };
-      warn $@ if $@ && $self->opt_v;
+      warn $@ if $@ && $self->opt_D;
     }
   }
   
@@ -1742,7 +1828,45 @@ sub drop_privs_maybe {
 
 __END__
 
-# See "perldoc perldoc" for basic details.
+=head1 NAME
+
+Pod::Perldoc - Look up Perl documentation in Pod format.
+
+=head1 SYNOPSIS
+
+    use Pod::Perldoc ();
+
+    Pod::Perldoc->run();
+
+=head1 DESCRIPTION
+
+The guts of L<perldoc> utility.
+
+=head1 SEE ALSO
+
+L<perldoc>
+
+=head1 COPYRIGHT AND DISCLAIMERS
+
+Copyright (c) 2002-2007 Sean M. Burke.
+
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+This program is distributed in the hope that it will be useful, but
+without any warranty; without even the implied warranty of
+merchantability or fitness for a particular purpose.
+
+=head1 AUTHOR
+
+Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
+
+Past contributions from:
+Sean M. Burke <sburke@cpan.org>
+
+=cut
+
+# 
 #
 # Perldoc -- look up a piece of documentation in .pod format that
 # is embedded in the perl installation tree.
diff --git a/lib/Pod/Perldoc/BaseTo.pm b/lib/Pod/Perldoc/BaseTo.pm
index 6ca2a8c7e5..29a3b7d108 100644
--- a/lib/Pod/Perldoc/BaseTo.pm
+++ b/lib/Pod/Perldoc/BaseTo.pm
@@ -26,3 +26,56 @@ sub _perldoc_elem {
 
 1;
 
+__END__
+
+=head1 NAME
+
+Pod::Perldoc::BaseTo - Base for Pod::Perldoc formatters
+
+=head1 SYNOPSIS
+
+    package Pod::Perldoc::ToMyFormat;
+
+    use base qw( Pod::Perldoc::BaseTo );
+    ...
+
+=head1 DESCRIPTION
+
+This package is meant as a base of Pod::Perldoc formatters,
+like L<Pod::Perldoc::ToText>, L<Pod::Perldoc::ToMan>, etc.
+
+It provides default implementations for the methods
+
+    is_pageable
+    write_with_binmode
+    output_extension
+    _perldoc_elem
+
+The concrete formatter must implement
+
+    new
+    parse_from_file
+
+=head1 SEE ALSO
+
+L<perldoc>
+
+=head1 COPYRIGHT AND DISCLAIMERS
+
+Copyright (c) 2002-2007 Sean M. Burke.
+
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+This program is distributed in the hope that it will be useful, but
+without any warranty; without even the implied warranty of
+merchantability or fitness for a particular purpose.
+
+=head1 AUTHOR
+
+Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
+
+Past contributions from:
+Sean M. Burke <sburke@cpan.org>
+
+=cut
diff --git a/lib/Pod/Perldoc/GetOptsOO.pm b/lib/Pod/Perldoc/GetOptsOO.pm
index b29aeb1090..fa83fb74cc 100644
--- a/lib/Pod/Perldoc/GetOptsOO.pm
+++ b/lib/Pod/Perldoc/GetOptsOO.pm
@@ -104,3 +104,45 @@ sub getopts {
 
 1;
 
+__END__
+
+=head1 NAME
+
+Pod::Perldoc::GetOptsOO - Customized option parser for Pod::Perldoc
+
+=head1 SYNOPSIS
+
+    use Pod::Perldoc::GetOptsOO ();
+
+    Pod::Perldoc::GetOptsOO::getopts( $obj, \@args, $truth )
+       or die "wrong usage";
+
+
+=head1 DESCRIPTION
+
+Implements a customized option parser used for
+L<Pod::Perldoc>.
+
+=head1 SEE ALSO
+
+    Pod::Perldoc
+
+=head1 COPYRIGHT AND DISCLAIMERS
+
+Copyright (c) 2002-2007 Sean M. Burke.
+
+This library is free software; you can redistribute it and/or modify it
+under the same terms as Perl itself.
+
+This program is distributed in the hope that it will be useful, but
+without any warranty; without even the implied warranty of
+merchantability or fitness for a particular purpose.
+
+=head1 AUTHOR
+
+Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
+
+Past contributions from:
+Sean M. Burke <sburke@cpan.org>
+
+=cut
diff --git a/lib/Pod/Perldoc/ToChecker.pm b/lib/Pod/Perldoc/ToChecker.pm
index c60290d650..10870109e6 100644
--- a/lib/Pod/Perldoc/ToChecker.pm
+++ b/lib/Pod/Perldoc/ToChecker.pm
@@ -66,7 +66,10 @@ merchantability or fitness for a particular purpose.
 
 =head1 AUTHOR
 
-Sean M. Burke C<sburke@cpan.org>
+Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
+
+Past contributions from:
+Sean M. Burke <sburke@cpan.org>
 
 =cut
 
diff --git a/lib/Pod/Perldoc/ToMan.pm b/lib/Pod/Perldoc/ToMan.pm
index 4319122237..09b0e81737 100644
--- a/lib/Pod/Perldoc/ToMan.pm
+++ b/lib/Pod/Perldoc/ToMan.pm
@@ -181,7 +181,10 @@ merchantability or fitness for a particular purpose.
 
 =head1 AUTHOR
 
-Sean M. Burke C<sburke@cpan.org>
+Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
+
+Past contributions from:
+Sean M. Burke <sburke@cpan.org>
 
 =cut
 
diff --git a/lib/Pod/Perldoc/ToNroff.pm b/lib/Pod/Perldoc/ToNroff.pm
index d056860506..991c1e3269 100644
--- a/lib/Pod/Perldoc/ToNroff.pm
+++ b/lib/Pod/Perldoc/ToNroff.pm
@@ -94,7 +94,10 @@ merchantability or fitness for a particular purpose.
 
 =head1 AUTHOR
 
-Sean M. Burke C<sburke@cpan.org>
+Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
+
+Past contributions from:
+Sean M. Burke <sburke@cpan.org>
 
 =cut
 
diff --git a/lib/Pod/Perldoc/ToPod.pm b/lib/Pod/Perldoc/ToPod.pm
index bccbfcadbd..c3173d4370 100644
--- a/lib/Pod/Perldoc/ToPod.pm
+++ b/lib/Pod/Perldoc/ToPod.pm
@@ -84,7 +84,10 @@ merchantability or fitness for a particular purpose.
 
 =head1 AUTHOR
 
-Sean M. Burke C<sburke@cpan.org>
+Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
+
+Past contributions from:
+Sean M. Burke <sburke@cpan.org>
 
 =cut
 
diff --git a/lib/Pod/Perldoc/ToRtf.pm b/lib/Pod/Perldoc/ToRtf.pm
index 25e609e313..14d419fc31 100644
--- a/lib/Pod/Perldoc/ToRtf.pm
+++ b/lib/Pod/Perldoc/ToRtf.pm
@@ -79,7 +79,10 @@ merchantability or fitness for a particular purpose.
 
 =head1 AUTHOR
 
-Sean M. Burke C<sburke@cpan.org>
+Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
+
+Past contributions from:
+Sean M. Burke <sburke@cpan.org>
 
 =cut
 
diff --git a/lib/Pod/Perldoc/ToText.pm b/lib/Pod/Perldoc/ToText.pm
index 2eb9e0644a..7d1784cd59 100644
--- a/lib/Pod/Perldoc/ToText.pm
+++ b/lib/Pod/Perldoc/ToText.pm
@@ -85,7 +85,11 @@ merchantability or fitness for a particular purpose.
 
 =head1 AUTHOR
 
-Sean M. Burke C<sburke@cpan.org>
+Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
+
+Past contributions from:
+Sean M. Burke <sburke@cpan.org>
+
 
 =cut
 
diff --git a/lib/Pod/Perldoc/ToTk.pm b/lib/Pod/Perldoc/ToTk.pm
index 3945962950..1562ec8bb3 100644
--- a/lib/Pod/Perldoc/ToTk.pm
+++ b/lib/Pod/Perldoc/ToTk.pm
@@ -122,6 +122,9 @@ L<Tk::Pod>, L<Pod::Perldoc>
 
 =head1 AUTHOR
 
+Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
+
+Past contributions from:
 Sean M. Burke C<sburke@cpan.org>, with significant portions copied from
 F<tkpod> in the Tk::Pod dist, by Nick Ing-Simmons, Slaven Rezic, et al.
 
diff --git a/lib/Pod/Perldoc/ToXml.pm b/lib/Pod/Perldoc/ToXml.pm
index dd0d15cc10..439e736c20 100644
--- a/lib/Pod/Perldoc/ToXml.pm
+++ b/lib/Pod/Perldoc/ToXml.pm
@@ -57,7 +57,10 @@ merchantability or fitness for a particular purpose.
 
 =head1 AUTHOR
 
-Sean M. Burke C<sburke@cpan.org>
+Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
+
+Past contributions from:
+Sean M. Burke <sburke@cpan.org>
 
 =cut