From: Perl 5 Porters Date: Wed, 20 Mar 1996 02:31:34 +0000 (+0000) Subject: Use $^O, update VMS support, add -m, and move docs to bottom X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=7eda7aea6048cfa87ce1608689175b7c5e8a7370;p=p5sagit%2Fp5-mst-13.2.git Use $^O, update VMS support, add -m, and move docs to bottom --- diff --git a/utils/perldoc.PL b/utils/perldoc.PL index cfe6e2c..e53d542 100644 --- a/utils/perldoc.PL +++ b/utils/perldoc.PL @@ -15,8 +15,7 @@ use File::Basename qw(&basename &dirname); chdir(dirname($0)); ($file = basename($0)) =~ s/\.PL$//; $file =~ s/\.pl$// - if ($Config{'osname'} eq 'VMS' or - $Config{'osname'} eq 'OS2'); # "case-forgiving" + if ($^O eq 'VMS' or $^O eq 'os2'); # "case-forgiving" open OUT,">$file" or die "Can't create $file: $!"; @@ -44,108 +43,10 @@ print OUT <<'!NO!SUBS!'; # This is not to be confused with Tom Christianson's perlman, which is a # man replacement, written in perl. This perldoc is strictly for reading # the perl manuals, though it too is written in perl. -# -# Version 1.11: Tue Dec 26 09:54:33 EST 1995 -# Kenneth Albanowski -# -added Charles Bailey's further VMS patches, and -u switch -# -added -t switch, with pod2text support -# -# Version 1.10: Thu Nov 9 07:23:47 EST 1995 -# Kenneth Albanowski -# -added VMS support -# -added better error recognition (on no found pages, just exit. On -# missing nroff/pod2man, just display raw pod.) -# -added recursive/case-insensitive matching (thanks, Andreas). This -# slows things down a bit, unfortunately. Give a precise name, and -# it'll run faster. -# -# Version 1.01: Tue May 30 14:47:34 EDT 1995 -# Andy Dougherty -# -added pod documentation. -# -added PATH searching. -# -added searching pod/ subdirectory (mainly to pick up perlfunc.pod -# and friends. -# -# -# TODO: -# -# Cache directories read during sloppy match -# - -=head1 NAME - -perldoc - Look up Perl documentation in pod format. - -=head1 SYNOPSIS - -B [B<-h>] [B<-v>] [B<-t>] [B<-u>] PageName|ModuleName|ProgramName - -=head1 DESCRIPTION - -I looks up a piece of documentation in .pod format that is -embedded in the perl installation tree or in a perl script, and displays -it via pod2man | nroff -man | $PAGER. This is primarily used for the -documentation for the perl library modules. - -Your system may also have man pages installed for those modules, in -which case you can probably just use the man(1) command. - -=head1 OPTIONS - -=over 5 - -=item B<-h> help - -Prints out a brief help message. - -=item B<-v> verbose - -Describes search for the item in detail. - -=item B<-t> text output - -Display docs using plain text converter, instead of nroff. This may be faster, -but it won't look as nice. - -=item B<-u> unformatted - -Find docs only; skip reformatting by pod2* - -=item B - -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. You make also give a -partial or wrong-case name, such as "basename" for "File::Basename", but -this will be slower, if there is more then one page with the same partial -name, you will only get the first one. - -=back - -=head1 ENVIRONMENT - -Any switches in the C environment variable will be used before the -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.) - -=head1 AUTHOR - -Kenneth Albanowski - -Minor updates by Andy Dougherty - -=head1 SEE ALSO - -=head1 DIAGNOSTICS - -=cut if(@ARGV<1) { die < 1; -@pages = @ARGV; +if ($opt_t) { require Pod::Text; import Pod::Text; } -# VMS only -- use this hack until support for searchlist -# logical names is better integrated into the Perl core -sub translate_searchlist_logical { - my($lnm) = @_; - my($trans,@trans); - return unless $ENV{$lnm}; - $trans = `show logical $lnm`; - $trans =~ s/\n1(.|\n)*//; # clip off iterative translations - @trans = split(/[\"=\s\n]+/,$trans); # break into words - splice(@trans,0,2); # pop off initial blank and orig name - @trans = grep(!/^\(/,@trans); # filter out table names - wantarray ? @trans : $trans[0]; -} +@pages = @ARGV; sub containspod { my($file) = @_; @@ -278,7 +167,7 @@ sub containspod { my(@newdirs) = grep(-d,map("$dir/$_",grep(!/^\.\.?$/,readdir(D)))); closedir(D); @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS; - last unless @newdirs; + next unless @newdirs; print STDERR "Also looking in @newdirs\n" if $opt_v; push(@dirs,@newdirs); } @@ -292,12 +181,17 @@ foreach (@pages) { # We must look both in @INC for library modules and in PATH # for executables, like h2xs or perldoc itself. @searchdirs = @INC; - if ($Is_VMS) { - push(@searchdirs, translate_searchlist_logical('DCL$PATH')); - } else { - push(@searchdirs, grep(-d, split(':', $ENV{'PATH'}))); + unless ($opt_m) { + if ($Is_VMS) { + my($i,$trn); + for ($i = 0; $trn = $ENV{'DCL$PATH'.$i}; $i++) { + push(@searchdirs,$trn); + } + } else { + push(@searchdirs, grep(-d, split(':', $ENV{'PATH'}))); + } + @files= searchfor(0,$_,@searchdirs); } - @files= searchfor(0,$_,@searchdirs); if( @files ) { print STDERR "Found as @files\n" if $opt_v; } else { @@ -334,8 +228,16 @@ unless($Is_VMS) { $goodresult = 1; } +if ($opt_m) { + foreach $pager (@pagers) { + my($sts) = system("$pager @found"); + exit 0 if ($Is_VMS ? ($sts & 1) : !$sts); + } + exit $Is_VMS ? $sts : 1; +} + foreach (@found) { - + if($opt_t) { open(TMP,">>$tmp"); Pod::Text::pod2text($_,*TMP); @@ -378,6 +280,113 @@ if( $opt_f ) { 1 while unlink($tmp); #Possibly pointless VMSism exit 0; + +__END__ + +=head1 NAME + +perldoc - Look up Perl documentation in pod format. + +=head1 SYNOPSIS + +B [B<-h>] [B<-v>] [B<-t>] [B<-u>] PageName|ModuleName|ProgramName + +=head1 DESCRIPTION + +I looks up a piece of documentation in .pod format that is +embedded in the perl installation tree or in a perl script, and displays +it via pod2man | nroff -man | $PAGER. This is primarily used for the +documentation for the perl library modules. + +Your system may also have man pages installed for those modules, in +which case you can probably just use the man(1) command. + +=head1 OPTIONS + +=over 5 + +=item B<-h> help + +Prints out a brief help message. + +=item B<-v> verbose + +Describes search for the item in detail. + +=item B<-t> text output + +Display docs using plain text converter, instead of nroff. This may be faster, +but it won't look as nice. + +=item B<-u> unformatted + +Find docs only; skip reformatting by pod2* + +=item B<-m> module + +Display the entire module: both code and unformatted pod documentation. +This may be useful if the docs don't explain a function in the detail +you need, and you'd like to inspect the code directly; perldoc will find +the file for you and simply hand it off for display. + +=item B + +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. You make also give a +partial or wrong-case name, such as "basename" for "File::Basename", but +this will be slower, if there is more then one page with the same partial +name, you will only get the first one. + +=back + +=head1 ENVIRONMENT + +Any switches in the C environment variable will be used before the +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.) + +=head1 AUTHOR + +Kenneth Albanowski + +Minor updates by Andy Dougherty + +=head1 SEE ALSO + +=head1 DIAGNOSTICS + +=cut + +# +# Version 1.11: Tue Dec 26 09:54:33 EST 1995 +# Kenneth Albanowski +# -added Charles Bailey's further VMS patches, and -u switch +# -added -t switch, with pod2text support +# +# Version 1.10: Thu Nov 9 07:23:47 EST 1995 +# Kenneth Albanowski +# -added VMS support +# -added better error recognition (on no found pages, just exit. On +# missing nroff/pod2man, just display raw pod.) +# -added recursive/case-insensitive matching (thanks, Andreas). This +# slows things down a bit, unfortunately. Give a precise name, and +# it'll run faster. +# +# Version 1.01: Tue May 30 14:47:34 EDT 1995 +# Andy Dougherty +# -added pod documentation. +# -added PATH searching. +# -added searching pod/ subdirectory (mainly to pick up perlfunc.pod +# and friends. +# +# +# TODO: +# +# Cache directories read during sloppy match !NO!SUBS! close OUT or die "Can't close $file: $!";