utils/perldoc.PL

   1 #!/usr/local/bin/perl
   2
   3 use Config;
   4 use File::Basename qw(&basename &dirname);
   5 use Cwd;
   6
   7 # List explicitly here the variables you want Configure to
   8 # generate.  Metaconfig only looks for shell variables, so you
   9 # have to mention them as if they were shell variables, not
  10 # %Config entries.  Thus you write
  11 #  $startperl
  12 # to ensure Configure will look for $Config{startperl}.
  13
  14 # This forces PL files to create target in same directory as PL file.
  15 # This is so that make depend always knows where to find PL derivatives.
  16 $origdir = cwd;
  17 chdir dirname($0);
  18 $file = basename($0, '.PL');
  19 $file .= '.com' if $^O eq 'VMS';
  20
  21 open OUT,">$file" or die "Can't create $file: $!";
  22
  23 print "Extracting $file (with variable substitutions)\n";
  24
  25 # In this section, perl variables will be expanded during extraction.
  26 # You can use $Config{...} to use Configure variables.
  27
  28 print OUT <<"!GROK!THIS!";
  29 $Config{startperl}
  30     eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
  31         if 0;
  32
  33 use strict;
  34 my \@pagers = ();
  35 push \@pagers, "$Config{'pager'}" if -x "$Config{'pager'}";
  36 !GROK!THIS!
  37
  38 # In the following, perl variables are not expanded during extraction.
  39
  40 print OUT <<'!NO!SUBS!';
  41
  42 #
  43 # Perldoc revision #1 -- look up a piece of documentation in .pod format that
  44 # is embedded in the perl installation tree.
  45 #
  46 # This is not to be confused with Tom Christianson's perlman, which is a
  47 # man replacement, written in perl. This perldoc is strictly for reading
  48 # the perl manuals, though it too is written in perl.
  49
  50 if (@ARGV<1) {
  51         my $me = $0;            # Editing $0 is unportable
  52         $me =~ s,.*/,,;
  53         die <<EOF;
  54 Usage: $me [-h] [-r] [-i] [-v] [-t] [-u] [-m] [-l] [-F] [-X] PageName|ModuleName|ProgramName
  55        $me -f PerlFunc
  56        $me -q FAQKeywords
  57
  58 The -h option prints more help.  Also try "perldoc perldoc" to get
  59 aquainted with the system.
  60 EOF
  61 }
  62
  63 use Getopt::Std;
  64 use Config '%Config';
  65
  66 my @global_found = ();
  67 my $global_target = "";
  68
  69 my $Is_VMS = $^O eq 'VMS';
  70 my $Is_MSWin32 = $^O eq 'MSWin32';
  71 my $Is_Dos = $^O eq 'dos';
  72
  73 sub usage{
  74     warn "@_\n" if @_;
  75     # Erase evidence of previous errors (if any), so exit status is simple.
  76     $! = 0;
  77     die <<EOF;
  78 perldoc [options] PageName|ModuleName|ProgramName...
  79 perldoc [options] -f BuiltinFunction
  80 perldoc [options] -q FAQRegex
  81
  82 Options:
  83     -h   Display this help message
  84     -r   Recursive search (slow)
  85     -i   Ignore case
  86     -t   Display pod using pod2text instead of pod2man and nroff
  87              (-t is the default on win32)
  88     -u   Display unformatted pod text
  89     -m   Display module's file in its entirety
  90     -l   Display the module's file name
  91     -F   Arguments are file names, not modules
  92     -v   Verbosely describe what's going on
  93     -X   use index if present (looks for pod.idx at $Config{archlib})
  94     -q   Search the text of questions (not answers) in perlfaq[1-9]
  95
  96 PageName|ModuleName...
  97          is the name of a piece of documentation that you want to look at. You
  98          may either give a descriptive name of the page (as in the case of
  99          `perlfunc') the name of a module, either like `Term::Info',
 100          `Term/Info', the partial name of a module, like `info', or
 101          `makemaker', or the name of a program, like `perldoc'.
 102
 103 BuiltinFunction
 104          is the name of a perl function.  Will extract documentation from
 105          `perlfunc'.
 106
 107 FAQRegex
 108          is a regex. Will search perlfaq[1-9] for and extract any
 109          questions that match.
 110
 111 Any switches in the PERLDOC environment variable will be used before the
 112 command line arguments.  The optional pod index file contains a list of
 113 filenames, one per line.
 114
 115 EOF
 116 }
 117
 118 if (defined $ENV{"PERLDOC"}) {
 119     require Text::ParseWords;
 120     unshift(@ARGV, Text::ParseWords::shellwords($ENV{"PERLDOC"}));
 121 }
 122 !NO!SUBS!
 123
 124 my $getopts = "mhtluvriFf:Xq:";
 125 print OUT <<"!GET!OPTS!";
 126
 127 use vars qw( @{[map "\$opt_$_", ($getopts =~ /\w/g)]} );
 128
 129 getopts("$getopts") || usage;
 130 !GET!OPTS!
 131
 132 print OUT <<'!NO!SUBS!';
 133
 134 usage if $opt_h;
 135
 136 my $podidx;
 137 if ($opt_X) {
 138     $podidx = "$Config{'archlib'}/pod.idx";
 139     $podidx = "" unless -f $podidx && -r _ && -M _ <= 7;
 140 }
 141
 142 if ((my $opts = do{ local $^W; $opt_t + $opt_u + $opt_m + $opt_l }) > 1) {
 143     usage("only one of -t, -u, -m or -l")
 144 }
 145 elsif ($Is_MSWin32
 146        || $Is_Dos
 147        || !(exists $ENV{TERM} && $ENV{TERM} !~ /dumb|emacs|none|unknown/i))
 148 {
 149     $opt_t = 1 unless $opts
 150 }
 151
 152 if ($opt_t) { require Pod::Text; import Pod::Text; }
 153
 154 my @pages;
 155 if ($opt_f) {
 156     @pages = ("perlfunc");
 157 }
 158 elsif ($opt_q) {
 159     @pages = ("perlfaq1" .. "perlfaq9");
 160 }
 161 else {
 162     @pages = @ARGV;
 163 }
 164
 165 # Does this look like a module or extension directory?
 166 if (-f "Makefile.PL") {
 167         # Add ., lib and blib/* libs to @INC (if they exist)
 168         unshift(@INC, '.');
 169         unshift(@INC, 'lib') if -d 'lib';
 170         require ExtUtils::testlib;
 171 }
 172
 173 sub containspod {
 174     my($file, $readit) = @_;
 175     return 1 if !$readit && $file =~ /\.pod$/i;
 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($dir,$file) = @_;
 190      my $path = join('/',$dir,$file);
 191      return $path if -f $path and -r _;
 192      if (!$opt_i or $Is_VMS or $Is_MSWin32 or $Is_Dos or $^O eq 'os2') {
 193         # on a case-forgiving file system or if case is important
 194         # that is it all we can do
 195         warn "Ignored $path: unreadable\n" if -f _;
 196         return '';
 197      }
 198      local *DIR;
 199      local($")="/";
 200      my @p = ($dir);
 201      my($p,$cip);
 202      foreach $p (split(/\//, $file)){
 203         my $try = "@p/$p";
 204         stat $try;
 205         if (-d _) {
 206             push @p, $p;
 207             if ( $p eq $global_target) {
 208                 my $tmp_path = join ('/', @p);
 209                 my $path_f = 0;
 210                 for (@global_found) {
 211                     $path_f = 1 if $_ eq $tmp_path;
 212                 }
 213                 push (@global_found, $tmp_path) unless $path_f;
 214                 print STDERR "Found as @p but directory\n" if $opt_v;
 215             }
 216         }
 217         elsif (-f _ && -r _) {
 218             return $try;
 219         }
 220         elsif (-f _) {
 221             warn "Ignored $try: unreadable\n";
 222         }
 223         else {
 224             my $found=0;
 225             my $lcp = lc $p;
 226             opendir DIR, "@p";
 227             while ($cip=readdir(DIR)) {
 228                 if (lc $cip eq $lcp){
 229                     $found++;
 230                     last;
 231                 }
 232             }
 233             closedir DIR;
 234             return "" unless $found;
 235             push @p, $cip;
 236             return "@p" if -f "@p" and -r _;
 237             warn "Ignored @p: unreadable\n" if -f _;
 238         }
 239      }
 240      return "";
 241 }
 242
 243
 244 sub check_file {
 245     my($dir,$file) = @_;
 246     if ($opt_m) {
 247         return minus_f_nocase($dir,$file);
 248     }
 249     else {
 250         my $path = minus_f_nocase($dir,$file);
 251         return $path if length $path and containspod($path);
 252     }
 253     return "";
 254 }
 255
 256
 257 sub searchfor {
 258     my($recurse,$s,@dirs) = @_;
 259     $s =~ s!::!/!g;
 260     $s = VMS::Filespec::unixify($s) if $Is_VMS;
 261     return $s if -f $s && containspod($s);
 262     printf STDERR "Looking for $s in @dirs\n" if $opt_v;
 263     my $ret;
 264     my $i;
 265     my $dir;
 266     $global_target = (split('/', $s))[-1];
 267     for ($i=0; $i<@dirs; $i++) {
 268         $dir = $dirs[$i];
 269         ($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
 270         if (       ( $ret = check_file $dir,"$s.pod")
 271                 or ( $ret = check_file $dir,"$s.pm")
 272                 or ( $ret = check_file $dir,$s)
 273                 or ( $Is_VMS and
 274                      $ret = check_file $dir,"$s.com")
 275                 or ( $^O eq 'os2' and
 276                      $ret = check_file $dir,"$s.cmd")
 277                 or ( ($Is_MSWin32 or $Is_Dos or $^O eq 'os2') and
 278                      $ret = check_file $dir,"$s.bat")
 279                 or ( $ret = check_file "$dir/pod","$s.pod")
 280                 or ( $ret = check_file "$dir/pod",$s)
 281         ) {
 282             return $ret;
 283         }
 284
 285         if ($recurse) {
 286             opendir(D,$dir);
 287             my @newdirs = map "$dir/$_", grep {
 288                 not /^\.\.?$/ and
 289                 not /^auto$/  and   # save time! don't search auto dirs
 290                 -d  "$dir/$_"
 291             } readdir D;
 292             closedir(D);
 293             next unless @newdirs;
 294             @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
 295             print STDERR "Also looking in @newdirs\n" if $opt_v;
 296             push(@dirs,@newdirs);
 297         }
 298     }
 299     return ();
 300 }
 301
 302 sub filter_nroff {
 303   my @data = split /\n{2,}/, shift;
 304   shift @data while @data and $data[0] !~ /\S/; # Go to header
 305   shift @data if @data and $data[0] =~ /Contributed\s+Perl/; # Skip header
 306   pop @data if @data and $data[-1] =~ /^\w/; # Skip footer, like
 307                                 # 28/Jan/99 perl 5.005, patch 53 1
 308   join "\n\n", @data;
 309 }
 310
 311 sub printout {
 312     my ($file, $tmp, $filter) = @_;
 313     my $err;
 314
 315     if ($opt_t) {
 316         open(TMP,">>$tmp")
 317                 or warn("Can't open $tmp: $!"), return;
 318         Pod::Text::pod2text($file,*TMP);
 319         close TMP;
 320     }
 321     elsif (not $opt_u) {
 322         my $cmd = "pod2man --lax $file | nroff -man";
 323         $cmd .= " | col -x" if $^O =~ /hpux/;
 324         my $rslt = `$cmd`;
 325         $rslt = filter_nroff($rslt) if $filter;
 326         unless (($err = $?)) {
 327             open(TMP,">>$tmp") or warn("Can't open $tmp: $!"), return;
 328             print TMP $rslt;
 329             close TMP;
 330         }
 331     }
 332     if ($opt_u or $err or -z $tmp) {
 333         open(OUT,">>$tmp") or warn("Can't open $tmp: $!"), return;
 334         open(IN,"<$file") or warn("Can't open $file: $!"), return;
 335         my $cut = 1;
 336         while (<IN>) {
 337             $cut = $1 eq 'cut' if /^=(\w+)/;
 338             next if $cut;
 339             print OUT;
 340         }
 341         close IN;
 342         close OUT;
 343     }
 344 }
 345
 346 sub page {
 347     my ($tmp, $no_tty, @pagers) = @_;
 348     if ($no_tty) {
 349         open(TMP,"<$tmp") or warn("Can't open $tmp: $!"), return;
 350         print while <TMP>;
 351         close TMP;
 352     }
 353     else {
 354         foreach my $pager (@pagers) {
 355             system("$pager $tmp") or last;
 356         }
 357     }
 358 }
 359
 360 sub cleanup {
 361     my @files = @_;
 362     for (@files) {
 363         1 while unlink($_); #Possibly pointless VMSism
 364     }
 365 }
 366
 367 sub safe_exit {
 368     my ($val, @files) = @_;
 369     cleanup(@files);
 370     exit $val;
 371 }
 372
 373 sub safe_die {
 374     my ($msg, @files) = @_;
 375     cleanup(@files);
 376     die $msg;
 377 }
 378
 379 my @found;
 380 foreach (@pages) {
 381     if ($podidx && open(PODIDX, $podidx)) {
 382         my $searchfor = $_;
 383         local($_);
 384         $searchfor =~ s,::,/,g;
 385         print STDERR "Searching for '$searchfor' in $podidx\n" if $opt_v;
 386         while (<PODIDX>) {
 387             chomp;
 388             push(@found, $_) if m,/$searchfor(?:\.(?:pod|pm))?$,i;
 389         }
 390         close(PODIDX);
 391         next;
 392     }
 393     print STDERR "Searching for $_\n" if $opt_v;
 394     # We must look both in @INC for library modules and in PATH
 395     # for executables, like h2xs or perldoc itself.
 396     my @searchdirs = @INC;
 397     if ($opt_F) {
 398         next unless -r;
 399         push @found, $_ if $opt_m or containspod($_);
 400         next;
 401     }
 402     unless ($opt_m) {
 403         if ($Is_VMS) {
 404             my($i,$trn);
 405             for ($i = 0; $trn = $ENV{'DCL$PATH;'.$i}; $i++) {
 406                 push(@searchdirs,$trn);
 407             }
 408             push(@searchdirs,'perl_root:[lib.pod]')  # installed pods
 409         }
 410         else {
 411             push(@searchdirs, grep(-d, split($Config{path_sep},
 412                                              $ENV{'PATH'})));
 413         }
 414     }
 415     my @files = searchfor(0,$_,@searchdirs);
 416     if (@files) {
 417         print STDERR "Found as @files\n" if $opt_v;
 418     }
 419     else {
 420         # no match, try recursive search
 421         @searchdirs = grep(!/^\.$/,@INC);
 422         @files= searchfor(1,$_,@searchdirs) if $opt_r;
 423         if (@files) {
 424             print STDERR "Loosely found as @files\n" if $opt_v;
 425         }
 426         else {
 427             print STDERR "No documentation found for \"$_\".\n";
 428             if (@global_found) {
 429                 print STDERR "However, try\n";
 430                 for my $dir (@global_found) {
 431                     opendir(DIR, $dir) or die "$!";
 432                     while (my $file = readdir(DIR)) {
 433                         next if ($file =~ /^\./);
 434                         $file =~ s/\.(pm|pod)$//;
 435                         print STDERR "\tperldoc $_\::$file\n";
 436                     }
 437                     closedir DIR;
 438                 }
 439             }
 440         }
 441     }
 442     push(@found,@files);
 443 }
 444
 445 if (!@found) {
 446     exit ($Is_VMS ? 98962 : 1);
 447 }
 448
 449 if ($opt_l) {
 450     print join("\n", @found), "\n";
 451     exit;
 452 }
 453
 454 my $lines = $ENV{LINES} || 24;
 455
 456 my $no_tty;
 457 if (! -t STDOUT) { $no_tty = 1 }
 458
 459 # until here we could simply exit or die
 460 # now we create temporary files that we have to clean up
 461 # namely $tmp, $buffer
 462
 463 my $tmp;
 464 my $buffer;
 465 if ($Is_MSWin32) {
 466     $tmp = "$ENV{TEMP}\\perldoc1.$$";
 467     $buffer = "$ENV{TEMP}\\perldoc1.b$$";
 468     push @pagers, qw( more< less notepad );
 469     unshift @pagers, $ENV{PAGER}  if $ENV{PAGER};
 470     for (@found) { s,/,\\,g }
 471 }
 472 elsif ($Is_VMS) {
 473     $tmp = 'Sys$Scratch:perldoc.tmp1_'.$$;
 474     $buffer = 'Sys$Scratch:perldoc.tmp1_b'.$$;
 475     push @pagers, qw( most more less type/page );
 476 }
 477 elsif ($Is_Dos) {
 478     $tmp = "$ENV{TEMP}/perldoc1.$$";
 479     $buffer = "$ENV{TEMP}/perldoc1.b$$";
 480     $tmp =~ tr!\\/!//!s;
 481     $buffer =~ tr!\\/!//!s;
 482     push @pagers, qw( less.exe more.com< );
 483     unshift @pagers, $ENV{PAGER}  if $ENV{PAGER};
 484 }
 485 else {
 486     if ($^O eq 'os2') {
 487       require POSIX;
 488       $tmp = POSIX::tmpnam();
 489       $buffer = POSIX::tmpnam();
 490       unshift @pagers, 'less', 'cmd /c more <';
 491     }
 492     else {
 493       $tmp = "/tmp/perldoc1.$$";
 494       $buffer = "/tmp/perldoc1.b$$";
 495     }
 496     push @pagers, qw( more less pg view cat );
 497     unshift @pagers, $ENV{PAGER}  if $ENV{PAGER};
 498 }
 499 unshift @pagers, $ENV{PERLDOC_PAGER} if $ENV{PERLDOC_PAGER};
 500
 501 # all exit calls from here on have to be safe_exit calls (see above)
 502 # and all die calls safe_die calls to guarantee removal of files and
 503 # dir as needed
 504
 505 if ($opt_m) {
 506     foreach my $pager (@pagers) {
 507         system("$pager @found") or safe_exit(0, $tmp, $buffer);
 508     }
 509     if ($Is_VMS) { eval 'use vmsish qw(status exit); exit $?' }
 510     # I don't get the line above. Please patch yourself as needed.
 511     safe_exit(1, $tmp, $buffer);
 512 }
 513
 514 my @pod;
 515 if ($opt_f) {
 516     my $perlfunc = shift @found;
 517     open(PFUNC, $perlfunc)
 518         or safe_die("Can't open $perlfunc: $!", $tmp, $buffer);
 519
 520     # Functions like -r, -e, etc. are listed under `-X'.
 521     my $search_string = ($opt_f =~ /^-[rwxoRWXOeszfdlpSbctugkTBMAC]$/)
 522                         ? 'I<-X' : $opt_f ;
 523
 524     # Skip introduction
 525     while (<PFUNC>) {
 526         last if /^=head2 Alphabetical Listing of Perl Functions/;
 527     }
 528
 529     # Look for our function
 530     my $found = 0;
 531     my $inlist = 0;
 532     while (<PFUNC>) {
 533         if (/^=item\s+\Q$search_string\E\b/o)  {
 534             $found = 1;
 535         }
 536         elsif (/^=item/) {
 537             last if $found > 1 and not $inlist;
 538         }
 539         next unless $found;
 540         if (/^=over/) {
 541             ++$inlist;
 542         }
 543         elsif (/^=back/) {
 544             --$inlist;
 545         }
 546         push @pod, $_;
 547         ++$found if /^\w/;      # found descriptive text
 548     }
 549     if (!@pod) {
 550         die "No documentation for perl function `$opt_f' found\n";
 551     }
 552 }
 553
 554 if ($opt_q) {
 555     local @ARGV = @found;       # I'm lazy, sue me.
 556     my $found = 0;
 557     my %found_in;
 558
 559     while (<>) {
 560         if (/^=head2\s+.*(?:$opt_q)/oi) {
 561             $found = 1;
 562             push @pod, "=head1 Found in $ARGV\n\n" unless $found_in{$ARGV}++;
 563         }
 564         elsif (/^=head2/) {
 565             $found = 0;
 566         }
 567         next unless $found;
 568         push @pod, $_;
 569     }
 570     if (!@pod) {
 571         safe_die("No documentation for perl FAQ keyword `$opt_q' found\n",
 572                  $tmp, $buffer);
 573     }
 574 }
 575
 576 my $filter;
 577
 578 if (@pod) {
 579     open(TMP,">$buffer") or safe_die("Can't open '$buffer': $!", $tmp, $buffer);
 580     print TMP "=over 8\n\n";
 581     print TMP @pod;
 582     print TMP "=back\n";
 583     close TMP;
 584     @found = $buffer;
 585     $filter = 1;
 586 }
 587
 588 foreach (@found) {
 589     printout($_, $tmp, $filter);
 590 }
 591 page($tmp, $no_tty, @pagers);
 592
 593 safe_exit(0, $tmp, $buffer);
 594
 595 __END__
 596
 597 =head1 NAME
 598
 599 perldoc - Look up Perl documentation in pod format.
 600
 601 =head1 SYNOPSIS
 602
 603 B<perldoc> [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] [B<-F>]  [B<-X>] PageName|ModuleName|ProgramName
 604
 605 B<perldoc> B<-f> BuiltinFunction
 606
 607 B<perldoc> B<-q> FAQ Keyword
 608
 609 =head1 DESCRIPTION
 610
 611 I<perldoc> looks up a piece of documentation in .pod format that is embedded
 612 in the perl installation tree or in a perl script, and displays it via
 613 C<pod2man | nroff -man | $PAGER>. (In addition, if running under HP-UX,
 614 C<col -x> will be used.) This is primarily used for the documentation for
 615 the perl library modules.
 616
 617 Your system may also have man pages installed for those modules, in
 618 which case you can probably just use the man(1) command.
 619
 620 =head1 OPTIONS
 621
 622 =over 5
 623
 624 =item B<-h> help
 625
 626 Prints out a brief help message.
 627
 628 =item B<-v> verbose
 629
 630 Describes search for the item in detail.
 631
 632 =item B<-t> text output
 633
 634 Display docs using plain text converter, instead of nroff. This may be faster,
 635 but it won't look as nice.
 636
 637 =item B<-u> unformatted
 638
 639 Find docs only; skip reformatting by pod2*
 640
 641 =item B<-m> module
 642
 643 Display the entire module: both code and unformatted pod documentation.
 644 This may be useful if the docs don't explain a function in the detail
 645 you need, and you'd like to inspect the code directly; perldoc will find
 646 the file for you and simply hand it off for display.
 647
 648 =item B<-l> file name only
 649
 650 Display the file name of the module found.
 651
 652 =item B<-F> file names
 653
 654 Consider arguments as file names, no search in directories will be performed.
 655
 656 =item B<-f> perlfunc
 657
 658 The B<-f> option followed by the name of a perl built in function will
 659 extract the documentation of this function from L<perlfunc>.
 660
 661 =item B<-q> perlfaq
 662
 663 The B<-q> option takes a regular expression as an argument.  It will search
 664 the question headings in perlfaq[1-9] and print the entries matching
 665 the regular expression.
 666
 667 =item B<-X> use an index if present
 668
 669 The B<-X> option looks for a entry whose basename matches the name given on the
 670 command line in the file C<$Config{archlib}/pod.idx>.  The pod.idx file should
 671 contain fully qualified filenames, one per line.
 672
 673 =item B<PageName|ModuleName|ProgramName>
 674
 675 The item you want to look up.  Nested modules (such as C<File::Basename>)
 676 are specified either as C<File::Basename> or C<File/Basename>.  You may also
 677 give a descriptive name of a page, such as C<perlfunc>. You may also give a
 678 partial or wrong-case name, such as "basename" for "File::Basename", but
 679 this will be slower, if there is more then one page with the same partial
 680 name, you will only get the first one.
 681
 682 =back
 683
 684 =head1 ENVIRONMENT
 685
 686 Any switches in the C<PERLDOC> environment variable will be used before the
 687 command line arguments.  C<perldoc> also searches directories
 688 specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
 689 defined) and C<PATH> environment variables.
 690 (The latter is so that embedded pods for executables, such as
 691 C<perldoc> itself, are available.)  C<perldoc> will use, in order of
 692 preference, the pager defined in C<PERLDOC_PAGER>, C<MANPAGER>, or
 693 C<PAGER> before trying to find a pager on its own.  (C<MANPAGER> is not
 694 used if C<perldoc> was told to display plain text or unformatted pod.)
 695
 696 One useful value for C<PERLDOC_PAGER> is C<less -+C -E>.
 697
 698 =head1 VERSION
 699
 700 This is perldoc v2.0.
 701
 702 =head1 AUTHOR
 703
 704 Kenneth Albanowski <kjahds@kjahds.com>
 705
 706 Minor updates by Andy Dougherty <doughera@lafcol.lafayette.edu>,
 707 and others.
 708
 709 =cut
 710
 711 #
 712 # Version 1.14: Wed Jul 15 01:50:20 EST 1998
 713 #       Robin Barker <rmb1@cise.npl.co.uk>
 714 #       -strict, -w cleanups
 715 # Version 1.13: Fri Feb 27 16:20:50 EST 1997
 716 #       Gurusamy Sarathy <gsar@umich.edu>
 717 #       -doc tweaks for -F and -X options
 718 # Version 1.12: Sat Apr 12 22:41:09 EST 1997
 719 #       Gurusamy Sarathy <gsar@umich.edu>
 720 #       -various fixes for win32
 721 # Version 1.11: Tue Dec 26 09:54:33 EST 1995
 722 #       Kenneth Albanowski <kjahds@kjahds.com>
 723 #   -added Charles Bailey's further VMS patches, and -u switch
 724 #   -added -t switch, with pod2text support
 725 #
 726 # Version 1.10: Thu Nov  9 07:23:47 EST 1995
 727 #               Kenneth Albanowski <kjahds@kjahds.com>
 728 #       -added VMS support
 729 #       -added better error recognition (on no found pages, just exit. On
 730 #        missing nroff/pod2man, just display raw pod.)
 731 #       -added recursive/case-insensitive matching (thanks, Andreas). This
 732 #        slows things down a bit, unfortunately. Give a precise name, and
 733 #        it'll run faster.
 734 #
 735 # Version 1.01: Tue May 30 14:47:34 EDT 1995
 736 #               Andy Dougherty  <doughera@lafcol.lafayette.edu>
 737 #   -added pod documentation.
 738 #   -added PATH searching.
 739 #   -added searching pod/ subdirectory (mainly to pick up perlfunc.pod
 740 #    and friends.
 741 #
 742 #
 743 # TODO:
 744 #
 745 #       Cache directories read during sloppy match
 746 !NO!SUBS!
 747
 748 close OUT or die "Can't close $file: $!";
 749 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
 750 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
 751 chdir $origdir;