From 37279817102d902b6f022c9ad69b7e6a9cb78183 Mon Sep 17 00:00:00 2001 From: Chris 'BinGOs' Williams Date: Mon, 6 Jan 2014 16:11:48 +0000 Subject: [PATCH] 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 --- Porting/Maintainers.pl | 2 +- cpan/Pod-Perldoc/lib/Pod/Perldoc.pm | 113 +++++++++++++++++++++++--- cpan/Pod-Perldoc/lib/Pod/Perldoc/BaseTo.pm | 3 +- cpan/Pod-Perldoc/lib/Pod/Perldoc/GetOptsOO.pm | 2 +- cpan/Pod-Perldoc/lib/Pod/Perldoc/ToANSI.pm | 2 +- cpan/Pod-Perldoc/lib/Pod/Perldoc/ToChecker.pm | 2 +- cpan/Pod-Perldoc/lib/Pod/Perldoc/ToMan.pm | 6 +- cpan/Pod-Perldoc/lib/Pod/Perldoc/ToNroff.pm | 2 +- cpan/Pod-Perldoc/lib/Pod/Perldoc/ToPod.pm | 2 +- cpan/Pod-Perldoc/lib/Pod/Perldoc/ToRtf.pm | 2 +- cpan/Pod-Perldoc/lib/Pod/Perldoc/ToTerm.pm | 2 +- cpan/Pod-Perldoc/lib/Pod/Perldoc/ToText.pm | 2 +- cpan/Pod-Perldoc/lib/Pod/Perldoc/ToTk.pm | 2 +- cpan/Pod-Perldoc/lib/Pod/Perldoc/ToXml.pm | 2 +- cpan/Pod-Perldoc/perldoc.pod | 10 +++ 15 files changed, 126 insertions(+), 28 deletions(-) diff --git a/Porting/Maintainers.pl b/Porting/Maintainers.pl index 433378c..e3a459e 100755 --- a/Porting/Maintainers.pl +++ b/Porting/Maintainers.pl @@ -924,7 +924,7 @@ use File::Glob qw(:case); }, 'Pod::Perldoc' => { - 'DISTRIBUTION' => 'MALLEN/Pod-Perldoc-3.20.tar.gz', + 'DISTRIBUTION' => 'MALLEN/Pod-Perldoc-3.21.tar.gz', 'FILES' => q[cpan/Pod-Perldoc], # in blead, the perldoc executable is generated by perldoc.PL diff --git a/cpan/Pod-Perldoc/lib/Pod/Perldoc.pm b/cpan/Pod-Perldoc/lib/Pod/Perldoc.pm index 9cdee80..363626f 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 () { # "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 80ffc80..10eb10d 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 5b90794..07e9b17 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 baaea03..263056c 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 6bf0cf8..43e136e 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 bdd0140..42d3f01 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 c9fa0fa..74f54cd 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 dc5523f..aeff83a 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 75ea630..11a7094 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 bdc5625..4ca61b6 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 b2861f3..5b024dd 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 8c1240a..37b0d3f 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 9de73fb..0c03614 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 55febc4..a626044 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 + +The B<-a> option followed by the name of a perl api function will +extract the documentation of this function from L. + +Example: + + perldoc -a newHV =item B<-v> I -- 2.7.4