utils/perldoc.PL

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