This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
update Pod-Perldoc to version 3.14_07
authorAdriano Ferreira <a.r.ferreira@gmail.com>
Sun, 8 Jun 2008 11:29:22 +0000 (08:29 -0300)
committerRafael Garcia-Suarez <rgarciasuarez@gmail.com>
Sun, 8 Jun 2008 15:10:28 +0000 (15:10 +0000)
From: "Adriano Ferreira" <aferreira@shopzilla.com>
Message-ID: <73ddeb6c0806080729n63fc806dq83287e57347a4b5f@mail.gmail.com>

p4raw-id: //depot/perl@34028

13 files changed:
Porting/Maintainers.pl
lib/Pod/Perldoc.pm
lib/Pod/Perldoc/BaseTo.pm
lib/Pod/Perldoc/GetOptsOO.pm
lib/Pod/Perldoc/ToChecker.pm
lib/Pod/Perldoc/ToMan.pm
lib/Pod/Perldoc/ToNroff.pm
lib/Pod/Perldoc/ToPod.pm
lib/Pod/Perldoc/ToRtf.pm
lib/Pod/Perldoc/ToText.pm
lib/Pod/Perldoc/ToTk.pm
lib/Pod/Perldoc/ToXml.pm
pod/perldoc.pod

index 5b7486f..e3146b2 100644 (file)
@@ -763,7 +763,7 @@ package Maintainers;
 
        'Pod::Perldoc' =>
                {
-               'MAINTAINER'    => 'osfameron',
+               'MAINTAINER'    => 'ferreira',
                'FILES'         => q[lib/Pod/Perldoc.pm lib/Pod/Perldoc],
                'CPAN'          => 1,
                },
index 9ed66e8..5569d9f 100644 (file)
@@ -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.
index 6ca2a8c..29a3b7d 100644 (file)
@@ -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
index b29aeb1..fa83fb7 100644 (file)
@@ -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
index c60290d..1087010 100644 (file)
@@ -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
 
index 4319122..09b0e81 100644 (file)
@@ -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
 
index d056860..991c1e3 100644 (file)
@@ -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
 
index bccbfca..c3173d4 100644 (file)
@@ -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
 
index 25e609e..14d419f 100644 (file)
@@ -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
 
index 2eb9e06..7d1784c 100644 (file)
@@ -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
 
index 3945962..1562ec8 100644 (file)
@@ -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.
 
index dd0d15c..439e736 100644 (file)
@@ -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
 
index 8e27d05..43471c9 100644 (file)
@@ -5,7 +5,7 @@ perldoc - Look up Perl documentation in Pod format.
 
 =head1 SYNOPSIS
 
-B<perldoc> [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] [B<-F>]
+B<perldoc> [B<-h>] [B<-D>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] [B<-F>]
 [B<-i>] [B<-V>] [B<-T>] [B<-r>]
 [B<-dI<destination_file>>]
 [B<-oI<formatname>>]
@@ -24,6 +24,8 @@ B<perldoc> B<-q> FAQ Keyword
 
 B<perldoc> B<-L> fr B<-q> FAQ Keyword
 
+B<perldoc> B<-v> PerlVariable
+
 See below for more description of the switches.
 
 =head1 DESCRIPTION
@@ -48,9 +50,9 @@ documentation, see the L<perltoc> page.
 
 Prints out a brief B<h>elp message.
 
-=item B<-v>
+=item B<-D>
 
-Describes search for the item in detail (B<v>erbosely).
+B<D>escribes search for the item in B<d>etail.
 
 =item B<-t>
 
@@ -85,11 +87,29 @@ Example:
 
       perldoc -f sprintf
 
+
 =item B<-q> I<perlfaq-search-regexp>
 
 The B<-q> option takes a regular expression as an argument.  It will search
 the B<q>uestion headings in perlfaq[1-9] and print the entries matching
-the regular expression.  Example: C<perldoc -q shuffle>
+the regular expression.
+
+Example:
+
+     perldoc -q shuffle
+
+
+=item B<-v> I<perlvar>
+
+The B<-v> option followed by the name of a Perl predefined variable will
+extract the documentation of this variable from L<perlvar>.
+
+Examples:
+
+     perldoc -v '$"'
+     perldoc -v @+
+     perldoc -v DATA
+
 
 =item B<-T>
 
@@ -166,6 +186,10 @@ The item you want to look up.  Nested modules (such as C<File::Basename>)
 are specified either as C<File::Basename> or C<File/Basename>.  You may also
 give a descriptive name of a page, such as C<perlfunc>.
 
+For simple names like 'foo', when the normal search fails to find
+a matching page, a search with the "perl" prefix is tried as well.
+So "perldoc intro" is enough to find/render "perlintro.pod".
+
 =item B<-n> I<some-formatter>
 
 Specify replacement for nroff
@@ -222,11 +246,19 @@ Having PERLDOCDEBUG set to a positive integer will make perldoc emit
 even more descriptive output than the C<-v> switch does -- the higher the
 number, the more it emits.
 
+
+=head1 CHANGES
+
+Up to 3.14_05, the switch B<-v> was used to produce verbose
+messages of B<perldoc> operation, which is now enabled by B<-D>.
+
+
 =head1 AUTHOR
 
-Current maintainer: Sean M. Burke, <sburke@cpan.org>
+Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
 
 Past contributors are:
+Sean M. Burke <sburke@cpan.org>,
 Kenneth Albanowski <kjahds@kjahds.com>,
 Andy Dougherty  <doughera@lafcol.lafayette.edu>,
 and many others.