home *** CD-ROM | disk | FTP | other *** search
/ Amiga Magazin: Amiga-CD 1996 July / AMIGA_1996_7.BIN / ausgabe_7_96 / pd-programmierung / perl5_002bin.lha / bin / perldoc < prev    next >
Text File  |  1996-03-27  |  9KB  |  348 lines
  1. #!/gnu/bin/perl
  2.     eval 'exec perl -S $0 "$@"'
  3.     if 0;
  4.     eval 'exec perl -S $0 "$@"'
  5.     if 0;
  6.  
  7. #
  8. # Perldoc revision #1 -- look up a piece of documentation in .pod format that
  9. # is embedded in the perl installation tree.
  10. #
  11. # This is not to be confused with Tom Christianson's perlman, which is a
  12. # man replacement, written in perl. This perldoc is strictly for reading
  13. # the perl manuals, though it too is written in perl.
  14. #
  15. # Version 1.11: Tue Dec 26 09:54:33 EST 1995
  16. #       Kenneth Albanowski <kjahds@kjahds.com>
  17. #   -added Charles Bailey's further VMS patches, and -u switch
  18. #   -added -t switch, with pod2text support
  19. # 
  20. # Version 1.10: Thu Nov  9 07:23:47 EST 1995
  21. #        Kenneth Albanowski <kjahds@kjahds.com>
  22. #    -added VMS support
  23. #    -added better error recognition (on no found pages, just exit. On
  24. #     missing nroff/pod2man, just display raw pod.)
  25. #    -added recursive/case-insensitive matching (thanks, Andreas). This
  26. #     slows things down a bit, unfortunately. Give a precise name, and
  27. #     it'll run faster.
  28. #
  29. # Version 1.01:    Tue May 30 14:47:34 EDT 1995
  30. #        Andy Dougherty  <doughera@lafcol.lafayette.edu>
  31. #   -added pod documentation.
  32. #   -added PATH searching.
  33. #   -added searching pod/ subdirectory (mainly to pick up perlfunc.pod
  34. #    and friends.
  35. #
  36. #
  37. # TODO:
  38. #
  39. #    Cache directories read during sloppy match
  40. #
  41.  
  42. =head1 NAME
  43.  
  44. perldoc - Look up Perl documentation in pod format.
  45.  
  46. =head1 SYNOPSIS
  47.  
  48. B<perldoc> [B<-h>] [B<-v>] [B<-t>] [B<-u>] PageName|ModuleName|ProgramName
  49.  
  50. =head1 DESCRIPTION
  51.  
  52. I<perldoc> looks up a piece of documentation in .pod format that is
  53. embedded in the perl installation tree or in a perl script, and displays
  54. it via pod2man | nroff -man | $PAGER.  This is primarily used for the
  55. documentation for the perl library modules. 
  56.  
  57. Your system may also have man pages installed for those modules, in
  58. which case you can probably just use the man(1) command.
  59.  
  60. =head1 OPTIONS
  61.  
  62. =over 5
  63.  
  64. =item B<-h> help
  65.  
  66. Prints out a brief help message.
  67.  
  68. =item B<-v> verbose
  69.  
  70. Describes search for the item in detail.
  71.  
  72. =item B<-t> text output
  73.  
  74. Display docs using plain text converter, instead of nroff. This may be faster,
  75. but it won't look as nice.
  76.  
  77. =item B<-u> unformatted
  78.  
  79. Find docs only; skip reformatting by pod2*
  80.  
  81. =item B<PageName|ModuleName|ProgramName>
  82.  
  83. The item you want to look up.  Nested modules (such as C<File::Basename>)
  84. are specified either as C<File::Basename> or C<File/Basename>.  You may also
  85. give a descriptive name of a page, such as C<perlfunc>. You make also give a
  86. partial or wrong-case name, such as "basename" for "File::Basename", but
  87. this will be slower, if there is more then one page with the same partial
  88. name, you will only get the first one.
  89.  
  90. =back
  91.  
  92. =head1 ENVIRONMENT
  93.  
  94. Any switches in the C<PERLDOC> environment variable will be used before the 
  95. command line arguments.  C<perldoc> also searches directories
  96. specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
  97. defined) and C<PATH> environment variables.
  98. (The latter is so that embedded pods for executables, such as
  99. C<perldoc> itself, are available.)
  100.  
  101. =head1 AUTHOR
  102.  
  103. Kenneth Albanowski <kjahds@kjahds.com>
  104.  
  105. Minor updates by Andy Dougherty <doughera@lafcol.lafayette.edu>
  106.  
  107. =head1 SEE ALSO
  108.  
  109. =head1 DIAGNOSTICS
  110.  
  111. =cut
  112.  
  113. if(@ARGV<1) {
  114.     die <<EOF;
  115. Usage: $0 [-h] [-v] [-t] [-u] PageName|ModuleName|ProgramName
  116.  
  117. We suggest you use "perldoc perldoc" to get aquainted 
  118. with the system.
  119. EOF
  120. }
  121.  
  122. use Getopt::Std;
  123. use Config;
  124. $Is_VMS = $Config{'osname'} eq 'VMS';
  125.  
  126. sub usage{
  127.         warn "@_\n" if @_;
  128.     die <<EOF;
  129. perldoc [-h] [-v] [-u] PageName|ModuleName|ProgramName...
  130.     -h   Display this help message.
  131.     -t   Display pod using pod2text instead of pod2man and nroff.
  132.     -u     Display unformatted pod text
  133.     -v     Verbosely describe what's going on.
  134. PageName|ModuleName...
  135.          is the name of a piece of documentation that you want to look at. You 
  136.          may either give a descriptive name of the page (as in the case of
  137.          `perlfunc') the name of a module, either like `Term::Info', 
  138.          `Term/Info', the partial name of a module, like `info', or 
  139.          `makemaker', or the name of a program, like `perldoc'.
  140.          
  141. Any switches in the PERLDOC environment variable will be used before the 
  142. command line arguments.
  143.  
  144. EOF
  145. }
  146.  
  147. use Text::ParseWords;
  148.  
  149.  
  150. unshift(@ARGV,shellwords($ENV{"PERLDOC"}));
  151.  
  152. getopts("htuv") || usage;
  153.  
  154. usage if $opt_h || $opt_h; # avoid -w warning
  155.  
  156. eval "use Pod::Text" if $opt_t;
  157.  
  158. @pages = @ARGV;
  159.  
  160. # VMS only -- use this hack until support for searchlist
  161. # logical names is better integrated into the Perl core
  162. sub translate_searchlist_logical {
  163.     my($lnm) = @_;
  164.     my($trans,@trans);
  165.     return unless $ENV{$lnm};
  166.     $trans = `show logical $lnm`;
  167.     $trans =~ s/\n1(.|\n)*//;  # clip off iterative translations
  168.     @trans = split(/[\"=\s\n]+/,$trans); # break into words
  169.     splice(@trans,0,2); # pop off initial blank and orig name
  170.     @trans = grep(!/^\(/,@trans); # filter out table names
  171.     wantarray ? @trans : $trans[0];
  172. }
  173.  
  174. sub containspod {
  175.     my($file) = @_;
  176.     local($_);
  177.     open(TEST,"<$file");
  178.     while(<TEST>) {
  179.         if(/^=head/) {
  180.             close(TEST);
  181.             return 1;
  182.         }
  183.     }
  184.     close(TEST);
  185.     return 0;
  186. }
  187.  
  188.  sub minus_f_nocase {
  189.      my($file) = @_;
  190.      local *DIR;
  191.      local($")="/";
  192.      my(@p,$p,$cip);
  193.      foreach $p (split(/\//, $file)){
  194.     if ($Is_VMS and not scalar @p) {
  195.         # VMS filesystems don't begin at '/'
  196.         push(@p,$p);
  197.         next;
  198.     }
  199.      if (-d ("@p/$p")){
  200.          push @p, $p;
  201.      } elsif (-f ("@p/$p")) {
  202.          return "@p/$p";
  203.      } else {
  204.          my $found=0;
  205.          my $lcp = lc $p;
  206.          opendir DIR, "@p";
  207.          while ($cip=readdir(DIR)) {
  208.         $cip =~ s/\.dir$// if $Is_VMS;
  209.          if (lc $cip eq $lcp){
  210.              $found++;
  211.              last;
  212.          }
  213.          }
  214.          closedir DIR;
  215.          return "" unless $found;
  216.          push @p, $cip;
  217.          return "@p" if -f "@p";
  218.      }
  219.      }
  220.      return; # is not a file
  221.  }
  222.  
  223.   sub searchfor {
  224.       my($recurse,$s,@dirs) = @_;
  225.       $s =~ s!::!/!g;
  226.       $s = VMS::Filespec::unixify($s) if $Is_VMS;
  227.       printf STDERR "looking for $s in @dirs\n" if $opt_v;
  228.      my $ret;
  229.      my $i;
  230.      my $dir;
  231.       for ($i=0;$i<@dirs;$i++) {
  232.           $dir = $dirs[$i];
  233.           ($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
  234.          if ((    $ret = minus_f_nocase "$dir/$s.pod")
  235.          or ( $ret = minus_f_nocase "$dir/$s.pm"  and containspod($ret))
  236.          or ( $ret = minus_f_nocase "$dir/$s"     and containspod($ret))
  237.          or ( $Is_VMS and 
  238.               $ret = minus_f_nocase "$dir/$s.com" and containspod($ret))
  239.          or ( $ret = minus_f_nocase "$dir/pod/$s.pod")
  240.          or ( $ret = minus_f_nocase "$dir/pod/$s" and containspod($ret)))
  241.          { return $ret; }
  242.          
  243.          if($recurse) {
  244.             opendir(D,$dir);
  245.             my(@newdirs) = grep(-d,map("$dir/$_",grep(!/^\.\.?$/,readdir(D))));
  246.             closedir(D);
  247.             @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
  248.             last unless @newdirs;
  249.             print STDERR "Also looking in @newdirs\n" if $opt_v;
  250.             push(@dirs,@newdirs);
  251.          }
  252.      }
  253.       return ();
  254.   }
  255.  
  256.  
  257. foreach (@pages) {
  258.     print STDERR "Searching for $_\n" if $opt_v;
  259.     # We must look both in @INC for library modules and in PATH
  260.     # for executables, like h2xs or perldoc itself.
  261.     @searchdirs = @INC;
  262.     if ($Is_VMS) {
  263.         push(@searchdirs, translate_searchlist_logical('DCL$PATH'));
  264.     } else {
  265.         push(@searchdirs, grep(-d, split(':', $ENV{'PATH'})));
  266.     }
  267.     @files= searchfor(0,$_,@searchdirs);
  268.     if( @files ) {
  269.         print STDERR "Found as @files\n" if $opt_v;
  270.     } else {
  271.         # no match, try recursive search
  272.         
  273.         @searchdirs = grep(!/^\.$/,@INC);
  274.         
  275.         
  276.         @files= searchfor(1,$_,@searchdirs);
  277.         if( @files ) {
  278.             print STDERR "Loosely found as @files\n" if $opt_v;
  279.         } else {
  280.             print STDERR "No documentation found for '$_'\n";
  281.         }
  282.     }
  283.     push(@found,@files);
  284. }
  285.  
  286. if(!@found) {
  287.     exit ($Is_VMS ? 98962 : 1);
  288. }
  289.  
  290. if( ! -t STDOUT ) { $opt_f = 1 }
  291.  
  292. unless($Is_VMS) {
  293.     $tmp = "/tmp/perldoc1.$$";
  294.     $goodresult = 0;
  295.     @pagers = qw( more less pg view cat );
  296.     unshift(@pagers,$ENV{PAGER}) if $ENV{PAGER};
  297. } else {
  298.     $tmp = 'Sys$Scratch:perldoc.tmp1_'.$$;
  299.     @pagers = qw( most more less type/page );
  300.     unshift(@pagers,$ENV{PERLDOC_PAGER}) if $ENV{PERLDOC_PAGER};
  301.     $goodresult = 1;
  302. }
  303.  
  304. foreach (@found) {
  305.     
  306.     if($opt_t) {
  307.         open(TMP,">>$tmp");
  308.         Pod::Text::pod2text($_,*TMP);
  309.         close(TMP);
  310.     } elsif(not $opt_u) {
  311.         open(TMP,">>$tmp");
  312.         $rslt = `pod2man $_ | nroff -man`;
  313.         if ($Is_VMS) { $err = !($? % 2) || $rslt =~ /IVVERB/; }
  314.         else      { $err = $?; }
  315.         print TMP $rslt unless $err;
  316.         close TMP;
  317.     }
  318.                                                     
  319.     if( $opt_u or $err or -z $tmp) {
  320.         open(OUT,">>$tmp");
  321.         open(IN,"<$_");
  322.         $cut = 1;
  323.         while (<IN>) {
  324.             $cut = $1 eq 'cut' if /^=(\w+)/;
  325.             next if $cut;
  326.             print OUT;
  327.         }
  328.         close(IN);
  329.         close(OUT);
  330.     }
  331. }
  332.  
  333. if( $opt_f ) {
  334.     open(TMP,"<$tmp");
  335.     print while <TMP>;
  336.     close(TMP);
  337. } else {
  338.     foreach $pager (@pagers) {
  339.         $sts = system("$pager $tmp");
  340.         last if $Is_VMS && ($sts & 1);
  341.         last unless $sts;
  342.     }
  343. }
  344.  
  345. 1 while unlink($tmp); #Possibly pointless VMSism
  346.  
  347. exit 0;
  348.