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