X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=utils%2Fperldoc.PL;h=ed533f518ff013b0621326ce1d5e67d69dfc10ec;hb=562a7b0c67b6218259506760bd4728f2f0c6093b;hp=129d985882892d620ab0afab7b72df583eda8432;hpb=137443ea0a858c43f5a720730cac6209a7d41948;p=p5sagit%2Fp5-mst-13.2.git diff --git a/utils/perldoc.PL b/utils/perldoc.PL index 129d985..ed533f5 100644 --- a/utils/perldoc.PL +++ b/utils/perldoc.PL @@ -2,6 +2,7 @@ use Config; use File::Basename qw(&basename &dirname); +use Cwd; # List explicitly here the variables you want Configure to # generate. Metaconfig only looks for shell variables, so you @@ -12,6 +13,7 @@ use File::Basename qw(&basename &dirname); # This forces PL files to create target in same directory as PL file. # This is so that make depend always knows where to find PL derivatives. +$origdir = cwd; chdir dirname($0); $file = basename($0, '.PL'); $file .= '.com' if $^O eq 'VMS'; @@ -26,9 +28,10 @@ print "Extracting $file (with variable substitutions)\n"; print OUT <<"!GROK!THIS!"; $Config{startperl} eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}' - if \$running_under_some_shell; + if 0; -\@pagers = (); +use strict; +my \@pagers = (); push \@pagers, "$Config{'pager'}" if -x "$Config{'pager'}"; !GROK!THIS! @@ -45,19 +48,27 @@ print OUT <<'!NO!SUBS!'; # the perl manuals, though it too is written in perl. if(@ARGV<1) { - $0 =~ s,.*/,,; + my $me = $0; # Editing $0 is unportable + $me =~ s,.*/,,; die < 1) { +if( (my $opts = do{ local $^W; $opt_t + $opt_u + $opt_m + $opt_l }) > 1) { usage("only one of -t, -u, -m or -l") -} elsif ($Is_MSWin32) { - $opt_t = 1 unless $opt_t + $opt_u + $opt_m + $opt_l; +} elsif ($Is_MSWin32 || $Is_Dos) { + $opt_t = 1 unless $opts } if ($opt_t) { require Pod::Text; import Pod::Text; } +my @pages; if ($opt_f) { @pages = ("perlfunc"); +} elsif ($opt_q) { + @pages = ("perlfaq1" .. "perlfaq9"); } else { @pages = @ARGV; } +# Does this look like a module or extension directory? +if (-f "Makefile.PL") { + # Add ., lib and blib/* libs to @INC (if they exist) + unshift(@INC, '.'); + unshift(@INC, 'lib') if -d 'lib'; + require ExtUtils::testlib; +} + sub containspod { - my($file) = @_; - local($_); - open(TEST,"<$file"); - while() { - if(/^=head/) { - close(TEST); - return 1; - } + my($file, $readit) = @_; + return 1 if !$readit && $file =~ /\.pod$/i; + local($_); + open(TEST,"<$file"); + while() { + if(/^=head/) { + close(TEST); + return 1; } - close(TEST); - return 0; + } + close(TEST); + return 0; } - sub minus_f_nocase { - my($file) = @_; +sub minus_f_nocase { + my($dir,$file) = @_; + my $path = join('/',$dir,$file); + return $path if -f $path and -r _; + if (!$opt_i or $Is_VMS or $Is_MSWin32 or $Is_Dos or $^O eq 'os2') { + # on a case-forgiving file system or if case is important + # that is it all we can do + warn "Ignored $path: unreadable\n" if -f _; + return ''; + } local *DIR; local($")="/"; - my(@p,$p,$cip); + my @p = ($dir); + my($p,$cip); foreach $p (split(/\//, $file)){ - if (($Is_VMS or $Is_MSWin32 or $^O eq 'os2') and not scalar @p) { - # VMSish filesystems don't begin at '/' - push(@p,$p); - next; - } - if (-d ("@p/$p")){ + my $try = "@p/$p"; + stat $try; + if (-d _){ push @p, $p; - } elsif (-f ("@p/$p")) { - return "@p/$p"; + if ( $p eq $global_target) { + my $tmp_path = join ('/', @p); + my $path_f = 0; + for (@global_found) { + $path_f = 1 if $_ eq $tmp_path; + } + push (@global_found, $tmp_path) unless $path_f; + print STDERR "Found as @p but directory\n" if $opt_v; + } + } elsif (-f _ && -r _) { + return $try; + } elsif (-f _) { + warn "Ignored $try: unreadable\n"; } else { my $found=0; my $lcp = lc $p; opendir DIR, "@p"; while ($cip=readdir(DIR)) { - $cip =~ s/\.dir$// if $Is_VMS; if (lc $cip eq $lcp){ $found++; last; @@ -161,80 +226,140 @@ sub containspod { closedir DIR; return "" unless $found; push @p, $cip; - return "@p" if -f "@p"; + return "@p" if -f "@p" and -r _; + warn "Ignored @p: unreadable\n" if -f _; } } - return; # is not a file - } - - sub searchfor { - my($recurse,$s,@dirs) = @_; - $s =~ s!::!/!g; - $s = VMS::Filespec::unixify($s) if $Is_VMS; - return $s if -f $s && containspod($s); - printf STDERR "looking for $s in @dirs\n" if $opt_v; - my $ret; - my $i; - my $dir; - for ($i=0;$i<@dirs;$i++) { - $dir = $dirs[$i]; - ($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS; - if (( $ret = minus_f_nocase "$dir/$s.pod") - or ( $ret = minus_f_nocase "$dir/$s.pm" and containspod($ret)) - or ( $ret = minus_f_nocase "$dir/$s" and containspod($ret)) - or ( $Is_VMS and - $ret = minus_f_nocase "$dir/$s.com" and containspod($ret)) - or ( $Is_MSWin32 and - $ret = minus_f_nocase "$dir/$s.bat" and containspod($ret)) - or ( $ret = minus_f_nocase "$dir/pod/$s.pod") - or ( $ret = minus_f_nocase "$dir/pod/$s" and containspod($ret))) - { return $ret; } - - if($recurse) { - opendir(D,$dir); - my(@newdirs) = grep(-d,map("$dir/$_",grep(!/^\.\.?$/,readdir(D)))); - closedir(D); - @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS; - next unless @newdirs; - print STDERR "Also looking in @newdirs\n" if $opt_v; - push(@dirs,@newdirs); - } - } - return (); - } + return ""; +} + + +sub check_file { + my($dir,$file) = @_; + if ($opt_m) { + return minus_f_nocase($dir,$file); + } else { + my $path = minus_f_nocase($dir,$file); + return $path if length $path and containspod($path); + } + return ""; +} +sub searchfor { + my($recurse,$s,@dirs) = @_; + $s =~ s!::!/!g; + $s = VMS::Filespec::unixify($s) if $Is_VMS; + return $s if -f $s && containspod($s); + printf STDERR "Looking for $s in @dirs\n" if $opt_v; + my $ret; + my $i; + my $dir; + $global_target = (split('/', $s))[-1]; + for ($i=0; $i<@dirs; $i++) { + $dir = $dirs[$i]; + ($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS; + if ( ( $ret = check_file $dir,"$s.pod") + or ( $ret = check_file $dir,"$s.pm") + or ( $ret = check_file $dir,$s) + or ( $Is_VMS and + $ret = check_file $dir,"$s.com") + or ( $^O eq 'os2' and + $ret = check_file $dir,"$s.cmd") + or ( ($Is_MSWin32 or $Is_Dos or $^O eq 'os2') and + $ret = check_file $dir,"$s.bat") + or ( $ret = check_file "$dir/pod","$s.pod") + or ( $ret = check_file "$dir/pod",$s) + ) { + return $ret; + } + + if ($recurse) { + opendir(D,$dir); + my @newdirs = map "$dir/$_", grep { + not /^\.\.?$/ and + not /^auto$/ and # save time! don't search auto dirs + -d "$dir/$_" + } readdir D; + closedir(D); + next unless @newdirs; + @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS; + print STDERR "Also looking in @newdirs\n" if $opt_v; + push(@dirs,@newdirs); + } + } + return (); +} + +sub filter_nroff { + my @data = split /\n{2,}/, shift; + shift @data while @data and $data[0] !~ /\S/; # Go to header + shift @data if @data and $data[0] =~ /Contributed\s+Perl/; # Skip header + pop @data if @data and $data[-1] =~ /^\w/; # Skip footer, like + # 28/Jan/99 perl 5.005, patch 53 1 + join "\n\n", @data; +} + +my @found; foreach (@pages) { + if ($podidx && open(PODIDX, $podidx)) { + my $searchfor = $_; + local($_); + $searchfor =~ s,::,/,g; + print STDERR "Searching for '$searchfor' in $podidx\n" if $opt_v; + while () { + chomp; + push(@found, $_) if m,/$searchfor(?:\.(?:pod|pm))?$,i; + } + close(PODIDX); + next; + } print STDERR "Searching for $_\n" if $opt_v; # We must look both in @INC for library modules and in PATH # for executables, like h2xs or perldoc itself. - @searchdirs = @INC; + my @searchdirs = @INC; + if ($opt_F) { + next unless -r; + push @found, $_ if $opt_m or containspod($_); + next; + } unless ($opt_m) { if ($Is_VMS) { my($i,$trn); - for ($i = 0; $trn = $ENV{'DCL$PATH'.$i}; $i++) { + for ($i = 0; $trn = $ENV{'DCL$PATH;'.$i}; $i++) { push(@searchdirs,$trn); } - } elsif ($Is_MSWin32) { - push(@searchdirs, grep(-d, split(';', $ENV{'PATH'}))); + push(@searchdirs,'perl_root:[lib.pod]') # installed pods } else { - push(@searchdirs, grep(-d, split(':', $ENV{'PATH'}))); + push(@searchdirs, grep(-d, split($Config{path_sep}, + $ENV{'PATH'}))); } - @files= searchfor(0,$_,@searchdirs); } + my @files = searchfor(0,$_,@searchdirs); if( @files ) { print STDERR "Found as @files\n" if $opt_v; } else { # no match, try recursive search - + @searchdirs = grep(!/^\.$/,@INC); - - - @files= searchfor(1,$_,@searchdirs); + + @files= searchfor(1,$_,@searchdirs) if $opt_r; if( @files ) { print STDERR "Loosely found as @files\n" if $opt_v; } else { - print STDERR "No documentation found for '$_'\n"; + print STDERR "No documentation found for \"$_\".\n"; + if (@global_found) { + print STDERR "However, try\n"; + for my $dir (@global_found) { + opendir(DIR, $dir) or die "$!"; + while (my $file = readdir(DIR)) { + next if ($file =~ /^\./); + $file =~ s/\.(pm|pod)$//; + print STDERR "\tperldoc $_\::$file\n"; + } + closedir DIR; + } + } } } push(@found,@files); @@ -249,8 +374,12 @@ if ($opt_l) { exit; } +my $lines = $ENV{LINES} || 24; + +my $no_tty; if( ! -t STDOUT ) { $no_tty = 1 } +my $tmp; if ($Is_MSWin32) { $tmp = "$ENV{TEMP}\\perldoc1.$$"; push @pagers, qw( more< less notepad ); @@ -258,25 +387,40 @@ if ($Is_MSWin32) { } elsif ($Is_VMS) { $tmp = 'Sys$Scratch:perldoc.tmp1_'.$$; push @pagers, qw( most more less type/page ); +} elsif ($Is_Dos) { + $tmp = "$ENV{TEMP}/perldoc1.$$"; + $tmp =~ tr!\\/!//!s; + push @pagers, qw( less.exe more.com< ); + unshift @pagers, $ENV{PAGER} if $ENV{PAGER}; } else { - $tmp = "/tmp/perldoc1.$$"; + if ($^O eq 'os2') { + require POSIX; + $tmp = POSIX::tmpnam(); + unshift @pagers, 'less', 'cmd /c more <'; + } else { + $tmp = "/tmp/perldoc1.$$"; + } push @pagers, qw( more less pg view cat ); unshift @pagers, $ENV{PAGER} if $ENV{PAGER}; } unshift @pagers, $ENV{PERLDOC_PAGER} if $ENV{PERLDOC_PAGER}; if ($opt_m) { - foreach $pager (@pagers) { + foreach my $pager (@pagers) { system("$pager @found") or exit; } if ($Is_VMS) { eval 'use vmsish qw(status exit); exit $?' } exit 1; -} +} +my @pod; if ($opt_f) { my $perlfunc = shift @found; open(PFUNC, $perlfunc) or die "Can't open $perlfunc: $!"; + # Functions like -r, -e, etc. are listed under `-X'. + my $search_string = ($opt_f =~ /^-[rwxoRWXOeszfdlpSbctugkTBMAC]$/) ? 'I<-X' : $opt_f ; + # Skip introduction while () { last if /^=head2 Alphabetical Listing of Perl Functions/; @@ -285,31 +429,58 @@ if ($opt_f) { # Look for our function my $found = 0; while () { - if (/^=item\s+\Q$opt_f\E\b/o) { - $found++; + if (/^=item\s+\Q$search_string\E\b/o) { + $found = 1; } elsif (/^=item/) { - last if $found; + last if $found > 1; } - push(@pod, $_) if $found; + next unless $found; + push @pod, $_; + ++$found if /^\w/; # found descriptive text } - if (@pod) { - if ($opt_t) { - open(FORMATTER, "| pod2text") || die "Can't start filter"; - print FORMATTER "=over 8\n\n"; - print FORMATTER @pod; - print FORMATTER "=back\n"; - close(FORMATTER); - } else { - print @pod; - } - } else { + if (!@pod) { die "No documentation for perl function `$opt_f' found\n"; } - exit; +} + +if ($opt_q) { + local @ARGV = @found; # I'm lazy, sue me. + my $found = 0; + my %found_in; + + while (<>) { + if (/^=head2\s+.*(?:$opt_q)/oi) { + $found = 1; + push @pod, "=head1 Found in $ARGV\n\n" unless $found_in{$ARGV}++; + } elsif (/^=head2/) { + $found = 0; + } + next unless $found; + push @pod, $_; + } + + if (!@pod) { + die "No documentation for perl FAQ keyword `$opt_q' found\n"; + } +} + +my $tmp1; +my $filter; + +if (@pod) { + $tmp1 = $tmp . "_"; + open(TMP,">$tmp1") or die "open '$tmp1': $!"; + print TMP "=over 8\n\n"; + print TMP @pod; + print TMP "=back\n"; + close(TMP) or die "close '$tmp1': $!"; + @found = $tmp1; + $filter = 1; } foreach (@found) { + my $err; if($opt_t) { open(TMP,">>$tmp"); Pod::Text::pod2text($_,*TMP); @@ -317,18 +488,19 @@ foreach (@found) { } elsif(not $opt_u) { my $cmd = "pod2man --lax $_ | nroff -man"; $cmd .= " | col -x" if $^O =~ /hpux/; - $rslt = `$cmd`; + my $rslt = `$cmd`; + $rslt = filter_nroff $rslt if $filter; unless(($err = $?)) { open(TMP,">>$tmp"); print TMP $rslt; close TMP; } } - + if( $opt_u or $err or -z $tmp) { open(OUT,">>$tmp"); open(IN,"<$_"); - $cut = 1; + my $cut = 1; while () { $cut = $1 eq 'cut' if /^=(\w+)/; next if $cut; @@ -344,12 +516,15 @@ if( $no_tty ) { print while ; close(TMP); } else { - foreach $pager (@pagers) { + foreach my $pager (@pagers) { system("$pager $tmp") or last; } } 1 while unlink($tmp); #Possibly pointless VMSism +if (defined $tmp1) { + 1 while unlink($tmp1); #Possibly pointless VMSism +} exit 0; @@ -361,10 +536,12 @@ perldoc - Look up Perl documentation in pod format. =head1 SYNOPSIS -B [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] PageName|ModuleName|ProgramName +B [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] [B<-F>] [B<-X>] PageName|ModuleName|ProgramName B B<-f> BuiltinFunction +B B<-q> FAQ Keyword + =head1 DESCRIPTION I looks up a piece of documentation in .pod format that is embedded @@ -408,11 +585,27 @@ the file for you and simply hand it off for display. Display the file name of the module found. +=item B<-F> file names + +Consider arguments as file names, no search in directories will be performed. + =item B<-f> perlfunc The B<-f> option followed by the name of a perl built in function will extract the documentation of this function from L. +=item B<-q> perlfaq + +The B<-q> option takes a regular expression as an argument. It will search +the question headings in perlfaq[1-9] and print the entries matching +the regular expression. + +=item B<-X> use an index if present + +The B<-X> option looks for a entry whose basename matches the name given on the +command line in the file C<$Config{archlib}/pod.idx>. The pod.idx file should +contain fully qualified filenames, one per line. + =item B The item you want to look up. Nested modules (such as C) @@ -431,7 +624,12 @@ command line arguments. C also searches directories specified by the C (or C if C is not defined) and C environment variables. (The latter is so that embedded pods for executables, such as -C itself, are available.) +C itself, are available.) C will use, in order of +preference, the pager defined in C, C, or +C before trying to find a pager on its own. (C is not +used if C was told to display plain text or unformatted pod.) + +One useful value for C is C. =head1 AUTHOR @@ -442,6 +640,12 @@ Minor updates by Andy Dougherty =cut # +# Version 1.14: Wed Jul 15 01:50:20 EST 1998 +# Robin Barker +# -strict, -w cleanups +# Version 1.13: Fri Feb 27 16:20:50 EST 1997 +# Gurusamy Sarathy +# -doc tweaks for -F and -X options # Version 1.12: Sat Apr 12 22:41:09 EST 1997 # Gurusamy Sarathy # -various fixes for win32 @@ -475,3 +679,4 @@ Minor updates by Andy Dougherty close OUT or die "Can't close $file: $!"; chmod 0755, $file or die "Can't reset permissions for $file: $!\n"; exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':'; +chdir $origdir;