From: Adriano Ferreira Date: Sun, 8 Jun 2008 11:29:22 +0000 (-0300) Subject: update Pod-Perldoc to version 3.14_07 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=91a462243ea69db634187747c3ddad662e832e86;p=p5sagit%2Fp5-mst-13.2.git update Pod-Perldoc to version 3.14_07 From: "Adriano Ferreira" Message-ID: <73ddeb6c0806080729n63fc806dq83287e57347a4b5f@mail.gmail.com> p4raw-id: //depot/perl@34028 --- diff --git a/Porting/Maintainers.pl b/Porting/Maintainers.pl index 5b7486f..e3146b2 100644 --- a/Porting/Maintainers.pl +++ b/Porting/Maintainers.pl @@ -763,7 +763,7 @@ package Maintainers; 'Pod::Perldoc' => { - 'MAINTAINER' => 'osfameron', + 'MAINTAINER' => 'ferreira', 'FILES' => q[lib/Pod/Perldoc.pm lib/Pod/Perldoc], 'CPAN' => 1, }, diff --git a/lib/Pod/Perldoc.pm b/lib/Pod/Perldoc.pm index 9ed66e8..5569d9f 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 = '$>'; + } + my $search_re = quotemeta($opt); + + DEBUG > 2 and + print "Going to perlvar-scan for $search_re in $perlvar\n"; + + # Skip introduction + local $_; + while () { + last if /^=over 8/; + } + + # Look for our variable + my $found = 0; + my $inheader = 1; + my $inlist = 0; + while () { # "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 utility. + +=head1 SEE ALSO + +L + +=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 + +Past contributions from: +Sean M. Burke + +=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 6ca2a8c..29a3b7d 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, L, 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 + +=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 + +Past contributions from: +Sean M. Burke + +=cut diff --git a/lib/Pod/Perldoc/GetOptsOO.pm b/lib/Pod/Perldoc/GetOptsOO.pm index b29aeb1..fa83fb7 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. + +=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 + +Past contributions from: +Sean M. Burke + +=cut diff --git a/lib/Pod/Perldoc/ToChecker.pm b/lib/Pod/Perldoc/ToChecker.pm index c60290d..1087010 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 +Current maintainer: Adriano R. Ferreira + +Past contributions from: +Sean M. Burke =cut diff --git a/lib/Pod/Perldoc/ToMan.pm b/lib/Pod/Perldoc/ToMan.pm index 4319122..09b0e81 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 +Current maintainer: Adriano R. Ferreira + +Past contributions from: +Sean M. Burke =cut diff --git a/lib/Pod/Perldoc/ToNroff.pm b/lib/Pod/Perldoc/ToNroff.pm index d056860..991c1e3 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 +Current maintainer: Adriano R. Ferreira + +Past contributions from: +Sean M. Burke =cut diff --git a/lib/Pod/Perldoc/ToPod.pm b/lib/Pod/Perldoc/ToPod.pm index bccbfca..c3173d4 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 +Current maintainer: Adriano R. Ferreira + +Past contributions from: +Sean M. Burke =cut diff --git a/lib/Pod/Perldoc/ToRtf.pm b/lib/Pod/Perldoc/ToRtf.pm index 25e609e..14d419f 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 +Current maintainer: Adriano R. Ferreira + +Past contributions from: +Sean M. Burke =cut diff --git a/lib/Pod/Perldoc/ToText.pm b/lib/Pod/Perldoc/ToText.pm index 2eb9e06..7d1784c 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 +Current maintainer: Adriano R. Ferreira + +Past contributions from: +Sean M. Burke + =cut diff --git a/lib/Pod/Perldoc/ToTk.pm b/lib/Pod/Perldoc/ToTk.pm index 3945962..1562ec8 100644 --- a/lib/Pod/Perldoc/ToTk.pm +++ b/lib/Pod/Perldoc/ToTk.pm @@ -122,6 +122,9 @@ L, L =head1 AUTHOR +Current maintainer: Adriano R. Ferreira + +Past contributions from: Sean M. Burke C, with significant portions copied from F 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 dd0d15c..439e736 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 +Current maintainer: Adriano R. Ferreira + +Past contributions from: +Sean M. Burke =cut diff --git a/pod/perldoc.pod b/pod/perldoc.pod index 8e27d05..43471c9 100644 --- a/pod/perldoc.pod +++ b/pod/perldoc.pod @@ -5,7 +5,7 @@ perldoc - Look up Perl documentation in Pod format. =head1 SYNOPSIS -B [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] [B<-F>] +B [B<-h>] [B<-D>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] [B<-F>] [B<-i>] [B<-V>] [B<-T>] [B<-r>] [B<-dI>] [B<-oI>] @@ -24,6 +24,8 @@ B B<-q> FAQ Keyword B B<-L> fr B<-q> FAQ Keyword +B B<-v> PerlVariable + See below for more description of the switches. =head1 DESCRIPTION @@ -48,9 +50,9 @@ documentation, see the L page. Prints out a brief Belp message. -=item B<-v> +=item B<-D> -Describes search for the item in detail (Berbosely). +Bescribes search for the item in Betail. =item B<-t> @@ -85,11 +87,29 @@ Example: perldoc -f sprintf + =item B<-q> I The B<-q> option takes a regular expression as an argument. It will search the Buestion headings in perlfaq[1-9] and print the entries matching -the regular expression. Example: C +the regular expression. + +Example: + + perldoc -q shuffle + + +=item B<-v> I + +The B<-v> option followed by the name of a Perl predefined variable will +extract the documentation of this variable from L. + +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) are specified either as C or C. You may also give a descriptive name of a page, such as C. +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 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 operation, which is now enabled by B<-D>. + + =head1 AUTHOR -Current maintainer: Sean M. Burke, +Current maintainer: Adriano R. Ferreira Past contributors are: +Sean M. Burke , Kenneth Albanowski , Andy Dougherty , and many others.