[perl5.git] / utils / perldoc.PL

#!/usr/local/bin/perl

use Config;
use File::Basename qw(&basename &dirname);

# List explicitly here the variables you want Configure to
# generate.  Metaconfig only looks for shell variables, so you
# have to mention them as if they were shell variables, not
# %Config entries.  Thus you write
#  $startperl
# to ensure Configure will look for $Config{startperl}.

# This forces PL files to create target in same directory as PL file.
# This is so that make depend always knows where to find PL derivatives.
chdir dirname($0);
$file = basename($0, '.PL');
$file .= '.com' if $^O eq 'VMS';

open OUT,">$file" or die "Can't create $file: $!";

print "Extracting $file (with variable substitutions)\n";

# In this section, perl variables will be expanded during extraction.
# You can use $Config{...} to use Configure variables.

print OUT <<"!GROK!THIS!";
$Config{startperl}
    eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
	if \$running_under_some_shell;

\@pagers = ();
push \@pagers, "$Config{'pager'}" if -x "$Config{'pager'}";
!GROK!THIS!

# In the following, perl variables are not expanded during extraction.

print OUT <<'!NO!SUBS!';

#
# Perldoc revision #1 -- look up a piece of documentation in .pod format that
# is embedded in the perl installation tree.
#
# 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.

if(@ARGV<1) {
	$me = $0;		# Editing $0 is unportable
	$me =~ s,.*/,,;
	die <<EOF;
Usage: $me [-h] [-v] [-t] [-u] [-m] [-l] PageName|ModuleName|ProgramName
       $me -f PerlFunc

We suggest you use "perldoc perldoc" to get aquainted 
with the system.
EOF
}

use Getopt::Std;
use Config '%Config';

@global_found = ();
$global_target = "";

$Is_VMS = $^O eq 'VMS';
$Is_MSWin32 = $^O eq 'MSWin32';

sub usage{
    warn "@_\n" if @_;
    # Erase evidence of previous errors (if any), so exit status is simple.
    $! = 0;
    die <<EOF;
perldoc [options] PageName|ModuleName|ProgramName...
perldoc [options] -f BuiltinFunction

Options:
    -h   Display this help message
    -t   Display pod using pod2text instead of pod2man and nroff
             (-t is the default on win32)
    -u	 Display unformatted pod text
    -m   Display modules file in its entirety
    -l   Display the modules file name
    -v	 Verbosely describe what's going on

PageName|ModuleName...
         is the name of a piece of documentation that you want to look at. You 
         may either give a descriptive name of the page (as in the case of
         `perlfunc') the name of a module, either like `Term::Info', 
         `Term/Info', the partial name of a module, like `info', or 
         `makemaker', or the name of a program, like `perldoc'.

BuiltinFunction
         is the name of a perl function.  Will extract documentation from
         `perlfunc'.
         
Any switches in the PERLDOC environment variable will be used before the 
command line arguments.

EOF
}

use Text::ParseWords;


unshift(@ARGV,shellwords($ENV{"PERLDOC"}));

getopts("mhtluvf:") || usage;

usage if $opt_h || $opt_h; # avoid -w warning

if ($opt_t + $opt_u + $opt_m + $opt_l > 1) {
    usage("only one of -t, -u, -m or -l")
} elsif ($Is_MSWin32) {
    $opt_t = 1 unless $opt_t + $opt_u + $opt_m + $opt_l;
}

if ($opt_t) { require Pod::Text; import Pod::Text; }

if ($opt_f) {
   @pages = ("perlfunc");
} else {
   @pages = @ARGV;
}

# Does this look like a module or extension directory?
if (-f "Makefile.PL") {
	# Add ., lib and blib/* libs to @INC (if they exist)
	unshift(@INC, '.');
	unshift(@INC, 'lib') if -d 'lib';
	require ExtUtils::testlib;
}


sub containspod {
    my($file, $readit) = @_;
    return 1 if !$readit && $file =~ /\.pod$/i;
    local($_);
    open(TEST,"<$file");
    while(<TEST>) {
	if(/^=head/) {
	    close(TEST);
	    return 1;
	}
    }
    close(TEST);
    return 0;
}

sub minus_f_nocase {
     my($file) = @_;
     # on a case-forgiving file system we can simply use -f $file
     if ($Is_VMS or $Is_MSWin32 or $^O eq 'os2') {
        return $file if -f $file and -r _;
	warn "Ignored $file: unreadable\n" unless -r _;
	return '';
     }
     local *DIR;
     local($")="/";
     my(@p,$p,$cip);
     foreach $p (split(/\//, $file)){
	my $try = "@p/$p";
	stat $try;
 	if (-d _){
 	    push @p, $p;
	    if ( $p eq $global_target) {
		$tmp_path = join ('/', @p);
		my $path_f = 0;
		for (@global_found) {
		    $path_f = 1 if $_ eq $tmp_path;
		}
		push (@global_found, $tmp_path) unless $path_f;
		print STDERR "Found as @p but directory\n" if $opt_v;
	    }
 	} elsif (-f _ && -r _) {
 	    return $try;
 	} elsif (-f _) {
	    warn "Ignored $try: unreadable\n";
 	} else {
 	    my $found=0;
 	    my $lcp = lc $p;
 	    opendir DIR, "@p";
 	    while ($cip=readdir(DIR)) {
 		if (lc $cip eq $lcp){
 		    $found++;
 		    last;
 		}
 	    }
 	    closedir DIR;
 	    return "" unless $found;
 	    push @p, $cip;
 	    return "@p" if -f "@p" and -r _;
	    warn "Ignored $file: unreadable\n" if -f _;
 	}
     }
     return; # is not a file
}
 

sub check_file {
    my($file) = @_;
    return minus_f_nocase($file) && containspod($file) ? $file : "";
}


sub searchfor {
    my($recurse,$s,@dirs) = @_;
    $s =~ s!::!/!g;
    $s = VMS::Filespec::unixify($s) if $Is_VMS;
    return $s if -f $s && containspod($s);
    printf STDERR "Looking for $s in @dirs\n" if $opt_v;
    my $ret;
    my $i;
    my $dir;
    $global_target = (split('/', $s))[-1];
    for ($i=0; $i<@dirs; $i++) {
	$dir = $dirs[$i];
	($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
	if (       ( $ret = check_file "$dir/$s.pod")
		or ( $ret = check_file "$dir/$s.pm")
		or ( $ret = check_file "$dir/$s")
		or ( $Is_VMS and
		     $ret = check_file "$dir/$s.com")
		or ( $^O eq 'os2' and 
		     $ret = check_file "$dir/$s.cmd")
		or ( ($Is_MSWin32 or $^O eq 'os2') and 
		     $ret = check_file "$dir/$s.bat")
		or ( $ret = check_file "$dir/pod/$s.pod")
		or ( $ret = check_file "$dir/pod/$s")
	) {
	    return $ret;
	}
	
	if ($recurse) {
	    opendir(D,$dir);
	    my @newdirs = map "$dir/$_", grep {
		not /^\.\.?$/ and
		not /^auto$/  and   # save time! don't search auto dirs
		-d  "$dir/$_"
	    } readdir D;
	    closedir(D);
	    next unless @newdirs;
	    @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
	    print STDERR "Also looking in @newdirs\n" if $opt_v;
	    push(@dirs,@newdirs);
	}
    }
    return ();
}


foreach (@pages) {
	print STDERR "Searching for $_\n" if $opt_v;
	# We must look both in @INC for library modules and in PATH
	# for executables, like h2xs or perldoc itself.
	@searchdirs = @INC;
	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($Config{path_sep}, 
						 $ENV{'PATH'})));
	    }
	    @files= searchfor(0,$_,@searchdirs);
	}
	if( @files ) {
		print STDERR "Found as @files\n" if $opt_v;
	} else {
		# no match, try recursive search
		
		@searchdirs = grep(!/^\.$/,@INC);
		
		@files= searchfor(1,$_,@searchdirs);
		if( @files ) {
			print STDERR "Loosely found as @files\n" if $opt_v;
		} else {
			print STDERR "No documentation found for \"$_\".\n";
			if (@global_found) {
			    print STDERR "However, try\n";
			    my $dir = $file = "";
			    for $dir (@global_found) {
				opendir(DIR, $dir) or die "$!";
				while ($file = readdir(DIR)) {
				    next if ($file =~ /^\./);
				    $file =~ s/\.(pm|pod)$//;
				    print STDERR "\tperldoc $_\::$file\n";
				}
				closedir DIR;
			    }
			}
		}
	}
	push(@found,@files);
}

if(!@found) {
	exit ($Is_VMS ? 98962 : 1);
}

if ($opt_l) {
    print join("\n", @found), "\n";
    exit;
}

if( ! -t STDOUT ) { $no_tty = 1 }

if ($Is_MSWin32) {
	$tmp = "$ENV{TEMP}\\perldoc1.$$";
	push @pagers, qw( more< less notepad );
	unshift @pagers, $ENV{PAGER}  if $ENV{PAGER};
} elsif ($Is_VMS) {
	$tmp = 'Sys$Scratch:perldoc.tmp1_'.$$;
	push @pagers, qw( most more less type/page );
} else {
	if ($^O eq 'os2') {
	  require POSIX;
	  $tmp = POSIX::tmpnam();
	} else {
	  $tmp = "/tmp/perldoc1.$$";	  
	}
	push @pagers, qw( more less pg view cat );
	unshift @pagers, $ENV{PAGER}  if $ENV{PAGER};
}
unshift @pagers, $ENV{PERLDOC_PAGER} if $ENV{PERLDOC_PAGER};

if ($opt_m) {
	foreach $pager (@pagers) {
		system("$pager @found") or exit;
	}
	if ($Is_VMS) { eval 'use vmsish qw(status exit); exit $?' }
	exit 1;
} 

if ($opt_f) {
   my $perlfunc = shift @found;
   open(PFUNC, $perlfunc) or die "Can't open $perlfunc: $!";

   # Skip introduction
   while (<PFUNC>) {
       last if /^=head2 Alphabetical Listing of Perl Functions/;
   }

   # Look for our function
   my $found = 0;
   my @pod;
   while (<PFUNC>) {
       if (/^=item\s+\Q$opt_f\E\b/o)  {
	   $found = 1;
       } elsif (/^=item/) {
	   last if $found > 1;
       }
       next unless $found;
       push @pod, $_;
       ++$found if /^\w/;	# found descriptive text
   }
   if (@pod) {
       if ($opt_t) {
	   open(FORMATTER, "| pod2text") || die "Can't start filter";
	   print FORMATTER "=over 8\n\n";
	   print FORMATTER @pod;
	   print FORMATTER "=back\n";
	   close(FORMATTER);
       } else {
	   print @pod;
       }
   } else {
       die "No documentation for perl function `$opt_f' found\n";
   }
   exit;
}

foreach (@found) {

	if($opt_t) {
		open(TMP,">>$tmp");
		Pod::Text::pod2text($_,*TMP);
		close(TMP);
	} elsif(not $opt_u) {
		my $cmd = "pod2man --lax $_ | nroff -man";
		$cmd .= " | col -x" if $^O =~ /hpux/;
		$rslt = `$cmd`;
		unless(($err = $?)) {
			open(TMP,">>$tmp");
			print TMP $rslt;
			close TMP;
		}
	}
	                                                
	if( $opt_u or $err or -z $tmp) {
		open(OUT,">>$tmp");
		open(IN,"<$_");
		$cut = 1;
		while (<IN>) {
			$cut = $1 eq 'cut' if /^=(\w+)/;
			next if $cut;
			print OUT;
		}
		close(IN);
		close(OUT);
	}
}

if( $no_tty ) {
	open(TMP,"<$tmp");
	print while <TMP>;
	close(TMP);
} else {
	foreach $pager (@pagers) {
		system("$pager $tmp") or last;
	}
}

1 while unlink($tmp); #Possibly pointless VMSism

exit 0;

__END__

=head1 NAME

perldoc - Look up Perl documentation in pod format.

=head1 SYNOPSIS

B<perldoc> [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] PageName|ModuleName|ProgramName

B<perldoc> B<-f> BuiltinFunction

=head1 DESCRIPTION

I<perldoc> 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
C<pod2man | nroff -man | $PAGER>. (In addition, if running under HP-UX,
C<col -x> will be used.) 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<-l> file name only

Display the file name of the module found.

=item B<-f> perlfunc

The B<-f> option followed by the name of a perl built in function will
extract the documentation of this function from L<perlfunc>.

=item B<PageName|ModuleName|ProgramName>

The item you want to look up.  Nested modules (such as C<File::Basename>)
are specified either as C<File::Basename> or C<File/Basename>.  You may also
give a descriptive name of a page, such as C<perlfunc>. 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<PERLDOC> environment variable will be used before the 
command line arguments.  C<perldoc> also searches directories
specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
defined) and C<PATH> environment variables.
(The latter is so that embedded pods for executables, such as
C<perldoc> itself, are available.)

=head1 AUTHOR

Kenneth Albanowski <kjahds@kjahds.com>

Minor updates by Andy Dougherty <doughera@lafcol.lafayette.edu>

=cut

#
# Version 1.12: Sat Apr 12 22:41:09 EST 1997
#       Gurusamy Sarathy <gsar@umich.edu>
#	-various fixes for win32
# Version 1.11: Tue Dec 26 09:54:33 EST 1995
#       Kenneth Albanowski <kjahds@kjahds.com>
#   -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 <kjahds@kjahds.com>
#	-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  <doughera@lafcol.lafayette.edu>
#   -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: $!";
chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
Commit	Line	Data
4633a7c4 LW	1	#!/usr/local/bin/perl
	2
	3	use Config;
	4	use File::Basename qw(&basename &dirname);
	5
85880f03	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
4633a7c4	10	# $startperl
85880f03	11	# to ensure Configure will look for $Config{startperl}.
4633a7c4 LW	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.
44a8e56a	15	chdir dirname($0);
44a8e56a	16	$file = basename($0, '.PL');
774d564b	17	$file .= '.com' if $^O eq 'VMS';
4633a7c4 LW	18
	19	open OUT,">$file" or die "Can't create $file: $!";
	20
	21	print "Extracting $file (with variable substitutions)\n";
	22
	23	# In this section, perl variables will be expanded during extraction.
	24	# You can use $Config{...} to use Configure variables.
	25
85880f03	26	print OUT <<"!GROK!THIS!";
5f05dabc	27	$Config{startperl}
	28	eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
	29	if \$running_under_some_shell;
55497cff	30
	31	\@pagers = ();
	32	push \@pagers, "$Config{'pager'}" if -x "$Config{'pager'}";
4633a7c4 LW	33	!GROK!THIS!
	34
	35	# In the following, perl variables are not expanded during extraction.
	36
	37	print OUT <<'!NO!SUBS!';
	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.
4633a7c4 LW	46
4633a7c4 LW	47	if(@ARGV<1) {
0b166b66	48	$me = $0; # Editing $0 is unportable
fb73857a	49	$me =~ s,.*/,,;
4633a7c4	50	die <<EOF;
0b166b66 IZ	51	Usage: $me [-h] [-v] [-t] [-u] [-m] [-l] PageName\|ModuleName\|ProgramName
0b166b66 IZ	52	$me -f PerlFunc
4633a7c4 LW	53
	54	We suggest you use "perldoc perldoc" to get aquainted
	55	with the system.
	56	EOF
	57	}
	58
	59	use Getopt::Std;
59586d77 IZ	60	use Config '%Config';
59586d77 IZ	61
fb73857a	62	@global_found = ();
	63	$global_target = "";
	64
7eda7aea	65	$Is_VMS = $^O eq 'VMS';
137443ea	66	$Is_MSWin32 = $^O eq 'MSWin32';
4633a7c4 LW	67
4633a7c4 LW	68	sub usage{
ff0cee69	69	warn "@_\n" if @_;
	70	# Erase evidence of previous errors (if any), so exit status is simple.
	71	$! = 0;
4633a7c4	72	die <<EOF;
31bdbec1 GA	73	perldoc [options] PageName\|ModuleName\|ProgramName...
	74	perldoc [options] -f BuiltinFunction
	75
	76	Options:
137443ea	77	-h Display this help message
	78	-t Display pod using pod2text instead of pod2man and nroff
	79	(-t is the default on win32)
85880f03	80	-u Display unformatted pod text
7eda7aea	81	-m Display modules file in its entirety
44a8e56a	82	-l Display the modules file name
137443ea	83	-v Verbosely describe what's going on
31bdbec1	84
4633a7c4 LW	85	PageName\|ModuleName...
	86	is the name of a piece of documentation that you want to look at. You
	87	may either give a descriptive name of the page (as in the case of
	88	`perlfunc') the name of a module, either like `Term::Info',
	89	`Term/Info', the partial name of a module, like `info', or
	90	`makemaker', or the name of a program, like `perldoc'.
31bdbec1 GA	91
	92	BuiltinFunction
	93	is the name of a perl function. Will extract documentation from
	94	`perlfunc'.
4633a7c4 LW	95
	96	Any switches in the PERLDOC environment variable will be used before the
	97	command line arguments.
	98
	99	EOF
	100	}
	101
	102	use Text::ParseWords;
	103
	104
	105	unshift(@ARGV,shellwords($ENV{"PERLDOC"}));
	106
31bdbec1	107	getopts("mhtluvf:") \|\| usage;
85880f03	108
85880f03	109	usage if $opt_h \|\| $opt_h; # avoid -w warning
4633a7c4	110
137443ea	111	if ($opt_t + $opt_u + $opt_m + $opt_l > 1) {
	112	usage("only one of -t, -u, -m or -l")
	113	} elsif ($Is_MSWin32) {
	114	$opt_t = 1 unless $opt_t + $opt_u + $opt_m + $opt_l;
	115	}
4633a7c4	116
7eda7aea	117	if ($opt_t) { require Pod::Text; import Pod::Text; }
4633a7c4	118
31bdbec1 GA	119	if ($opt_f) {
	120	@pages = ("perlfunc");
	121	} else {
	122	@pages = @ARGV;
	123	}
	124
fb73857a	125	# Does this look like a module or extension directory?
	126	if (-f "Makefile.PL") {
	127	# Add ., lib and blib/* libs to @INC (if they exist)
	128	unshift(@INC, '.');
	129	unshift(@INC, 'lib') if -d 'lib';
	130	require ExtUtils::testlib;
	131	}
	132
31bdbec1	133
85880f03	134
4633a7c4	135	sub containspod {
fb73857a	136	my($file, $readit) = @_;
	137	return 1 if !$readit && $file =~ /\.pod$/i;
	138	local($_);
	139	open(TEST,"<$file");
	140	while(<TEST>) {
	141	if(/^=head/) {
	142	close(TEST);
	143	return 1;
4633a7c4	144	}
fb73857a	145	}
	146	close(TEST);
	147	return 0;
4633a7c4 LW	148	}
4633a7c4 LW	149
84902520	150	sub minus_f_nocase {
4633a7c4	151	my($file) = @_;
84902520 TB	152	# on a case-forgiving file system we can simply use -f $file
84902520 TB	153	if ($Is_VMS or $Is_MSWin32 or $^O eq 'os2') {
fb73857a	154	return $file if -f $file and -r _;
	155	warn "Ignored $file: unreadable\n" unless -r _;
	156	return '';
84902520	157	}
4633a7c4 LW	158	local *DIR;
	159	local($")="/";
	160	my(@p,$p,$cip);
	161	foreach $p (split(/\//, $file)){
fb73857a	162	my $try = "@p/$p";
	163	stat $try;
	164	if (-d _){
4633a7c4	165	push @p, $p;
fb73857a	166	if ( $p eq $global_target) {
	167	$tmp_path = join ('/', @p);
	168	my $path_f = 0;
	169	for (@global_found) {
	170	$path_f = 1 if $_ eq $tmp_path;
	171	}
	172	push (@global_found, $tmp_path) unless $path_f;
	173	print STDERR "Found as @p but directory\n" if $opt_v;
	174	}
	175	} elsif (-f _ && -r _) {
	176	return $try;
	177	} elsif (-f _) {
	178	warn "Ignored $try: unreadable\n";
4633a7c4 LW	179	} else {
	180	my $found=0;
	181	my $lcp = lc $p;
	182	opendir DIR, "@p";
	183	while ($cip=readdir(DIR)) {
	184	if (lc $cip eq $lcp){
	185	$found++;
	186	last;
	187	}
	188	}
	189	closedir DIR;
	190	return "" unless $found;
	191	push @p, $cip;
fb73857a	192	return "@p" if -f "@p" and -r _;
fb73857a	193	warn "Ignored $file: unreadable\n" if -f _;
4633a7c4 LW	194	}
	195	}
	196	return; # is not a file
fb73857a	197	}
4633a7c4	198
fb73857a	199
	200	sub check_file {
	201	my($file) = @_;
	202	return minus_f_nocase($file) && containspod($file) ? $file : "";
	203	}
	204
	205
	206	sub searchfor {
	207	my($recurse,$s,@dirs) = @_;
	208	$s =~ s!::!/!g;
	209	$s = VMS::Filespec::unixify($s) if $Is_VMS;
	210	return $s if -f $s && containspod($s);
	211	printf STDERR "Looking for $s in @dirs\n" if $opt_v;
	212	my $ret;
	213	my $i;
	214	my $dir;
	215	$global_target = (split('/', $s))[-1];
	216	for ($i=0; $i<@dirs; $i++) {
	217	$dir = $dirs[$i];
	218	($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
	219	if ( ( $ret = check_file "$dir/$s.pod")
	220	or ( $ret = check_file "$dir/$s.pm")
	221	or ( $ret = check_file "$dir/$s")
	222	or ( $Is_VMS and
	223	$ret = check_file "$dir/$s.com")
59586d77	224	or ( $^O eq 'os2' and
fb73857a	225	$ret = check_file "$dir/$s.cmd")
59586d77	226	or ( ($Is_MSWin32 or $^O eq 'os2') and
fb73857a	227	$ret = check_file "$dir/$s.bat")
	228	or ( $ret = check_file "$dir/pod/$s.pod")
	229	or ( $ret = check_file "$dir/pod/$s")
	230	) {
	231	return $ret;
	232	}
	233
	234	if ($recurse) {
	235	opendir(D,$dir);
	236	my @newdirs = map "$dir/$_", grep {
	237	not /^\.\.?$/ and
	238	not /^auto$/ and # save time! don't search auto dirs
	239	-d "$dir/$_"
	240	} readdir D;
	241	closedir(D);
	242	next unless @newdirs;
	243	@newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
	244	print STDERR "Also looking in @newdirs\n" if $opt_v;
	245	push(@dirs,@newdirs);
	246	}
	247	}
	248	return ();
	249	}
4633a7c4 LW	250
	251
	252	foreach (@pages) {
	253	print STDERR "Searching for $_\n" if $opt_v;
	254	# We must look both in @INC for library modules and in PATH
	255	# for executables, like h2xs or perldoc itself.
	256	@searchdirs = @INC;
7eda7aea	257	unless ($opt_m) {
	258	if ($Is_VMS) {
	259	my($i,$trn);
	260	for ($i = 0; $trn = $ENV{'DCL$PATH'.$i}; $i++) {
	261	push(@searchdirs,$trn);
	262	}
	263	} else {
59586d77 IZ	264	push(@searchdirs, grep(-d, split($Config{path_sep},
59586d77 IZ	265	$ENV{'PATH'})));
7eda7aea	266	}
7eda7aea	267	@files= searchfor(0,$_,@searchdirs);
85880f03	268	}
4633a7c4 LW	269	if( @files ) {
	270	print STDERR "Found as @files\n" if $opt_v;
	271	} else {
	272	# no match, try recursive search
	273
	274	@searchdirs = grep(!/^\.$/,@INC);
	275
4633a7c4 LW	276	@files= searchfor(1,$_,@searchdirs);
4633a7c4 LW	277	if( @files ) {
85880f03	278	print STDERR "Loosely found as @files\n" if $opt_v;
4633a7c4	279	} else {
fb73857a	280	print STDERR "No documentation found for \"$_\".\n";
	281	if (@global_found) {
	282	print STDERR "However, try\n";
	283	my $dir = $file = "";
	284	for $dir (@global_found) {
	285	opendir(DIR, $dir) or die "$!";
	286	while ($file = readdir(DIR)) {
	287	next if ($file =~ /^\./);
	288	$file =~ s/\.(pm\|pod)$//;
	289	print STDERR "\tperldoc $_\::$file\n";
	290	}
	291	closedir DIR;
	292	}
	293	}
4633a7c4 LW	294	}
	295	}
	296	push(@found,@files);
	297	}
	298
	299	if(!@found) {
85880f03	300	exit ($Is_VMS ? 98962 : 1);
4633a7c4 LW	301	}
4633a7c4 LW	302
44a8e56a	303	if ($opt_l) {
	304	print join("\n", @found), "\n";
	305	exit;
	306	}
	307
31bdbec1	308	if( ! -t STDOUT ) { $no_tty = 1 }
4633a7c4	309
137443ea	310	if ($Is_MSWin32) {
	311	$tmp = "$ENV{TEMP}\\perldoc1.$$";
	312	push @pagers, qw( more< less notepad );
55497cff	313	unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
137443ea	314	} elsif ($Is_VMS) {
4633a7c4	315	$tmp = 'Sys$Scratch:perldoc.tmp1_'.$$;
55497cff	316	push @pagers, qw( most more less type/page );
137443ea	317	} else {
59586d77 IZ	318	if ($^O eq 'os2') {
	319	require POSIX;
	320	$tmp = POSIX::tmpnam();
	321	} else {
	322	$tmp = "/tmp/perldoc1.$$";
	323	}
137443ea	324	push @pagers, qw( more less pg view cat );
137443ea	325	unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
4633a7c4	326	}
44a8e56a	327	unshift @pagers, $ENV{PERLDOC_PAGER} if $ENV{PERLDOC_PAGER};
4633a7c4	328
7eda7aea	329	if ($opt_m) {
1e422769	330	foreach $pager (@pagers) {
	331	system("$pager @found") or exit;
	332	}
	333	if ($Is_VMS) { eval 'use vmsish qw(status exit); exit $?' }
	334	exit 1;
7eda7aea	335	}
7eda7aea	336
31bdbec1 GA	337	if ($opt_f) {
	338	my $perlfunc = shift @found;
	339	open(PFUNC, $perlfunc) or die "Can't open $perlfunc: $!";
	340
	341	# Skip introduction
	342	while (<PFUNC>) {
	343	last if /^=head2 Alphabetical Listing of Perl Functions/;
	344	}
	345
	346	# Look for our function
	347	my $found = 0;
fb73857a	348	my @pod;
31bdbec1 GA	349	while (<PFUNC>) {
31bdbec1 GA	350	if (/^=item\s+\Q$opt_f\E\b/o) {
fb73857a	351	$found = 1;
31bdbec1	352	} elsif (/^=item/) {
fb73857a	353	last if $found > 1;
31bdbec1	354	}
fb73857a	355	next unless $found;
	356	push @pod, $_;
	357	++$found if /^\w/; # found descriptive text
31bdbec1 GA	358	}
	359	if (@pod) {
	360	if ($opt_t) {
	361	open(FORMATTER, "\| pod2text") \|\| die "Can't start filter";
	362	print FORMATTER "=over 8\n\n";
	363	print FORMATTER @pod;
	364	print FORMATTER "=back\n";
	365	close(FORMATTER);
	366	} else {
	367	print @pod;
	368	}
	369	} else {
ed5c9e50	370	die "No documentation for perl function `$opt_f' found\n";
31bdbec1 GA	371	}
	372	exit;
	373	}
	374
4633a7c4	375	foreach (@found) {
7eda7aea	376
85880f03	377	if($opt_t) {
	378	open(TMP,">>$tmp");
	379	Pod::Text::pod2text($_,*TMP);
	380	close(TMP);
	381	} elsif(not $opt_u) {
1e422769	382	my $cmd = "pod2man --lax $_ \| nroff -man";
	383	$cmd .= " \| col -x" if $^O =~ /hpux/;
	384	$rslt = `$cmd`;
	385	unless(($err = $?)) {
	386	open(TMP,">>$tmp");
	387	print TMP $rslt;
	388	close TMP;
40fc7247	389	}
85880f03	390	}
4633a7c4	391
85880f03	392	if( $opt_u or $err or -z $tmp) {
4633a7c4 LW	393	open(OUT,">>$tmp");
4633a7c4 LW	394	open(IN,"<$_");
85880f03	395	$cut = 1;
	396	while (<IN>) {
	397	$cut = $1 eq 'cut' if /^=(\w+)/;
	398	next if $cut;
	399	print OUT;
	400	}
4633a7c4 LW	401	close(IN);
	402	close(OUT);
	403	}
	404	}
	405
31bdbec1	406	if( $no_tty ) {
4633a7c4 LW	407	open(TMP,"<$tmp");
	408	print while <TMP>;
	409	close(TMP);
	410	} else {
85880f03	411	foreach $pager (@pagers) {
1e422769	412	system("$pager $tmp") or last;
4633a7c4 LW	413	}
	414	}
	415
	416	1 while unlink($tmp); #Possibly pointless VMSism
	417
	418	exit 0;
7eda7aea	419
	420	__END__
	421
	422	=head1 NAME
	423
	424	perldoc - Look up Perl documentation in pod format.
	425
	426	=head1 SYNOPSIS
	427
44a8e56a	428	B<perldoc> [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] PageName\|ModuleName\|ProgramName
7eda7aea	429
31bdbec1 GA	430	B<perldoc> B<-f> BuiltinFunction
31bdbec1 GA	431
7eda7aea	432	=head1 DESCRIPTION
7eda7aea	433
40fc7247	434	I<perldoc> looks up a piece of documentation in .pod format that is embedded
	435	in the perl installation tree or in a perl script, and displays it via
	436	C<pod2man \| nroff -man \| $PAGER>. (In addition, if running under HP-UX,
	437	C<col -x> will be used.) This is primarily used for the documentation for
	438	the perl library modules.
7eda7aea	439
	440	Your system may also have man pages installed for those modules, in
	441	which case you can probably just use the man(1) command.
	442
	443	=head1 OPTIONS
	444
	445	=over 5
	446
	447	=item B<-h> help
	448
	449	Prints out a brief help message.
	450
	451	=item B<-v> verbose
	452
	453	Describes search for the item in detail.
	454
	455	=item B<-t> text output
	456
	457	Display docs using plain text converter, instead of nroff. This may be faster,
	458	but it won't look as nice.
	459
	460	=item B<-u> unformatted
	461
	462	Find docs only; skip reformatting by pod2*
	463
	464	=item B<-m> module
	465
	466	Display the entire module: both code and unformatted pod documentation.
	467	This may be useful if the docs don't explain a function in the detail
	468	you need, and you'd like to inspect the code directly; perldoc will find
	469	the file for you and simply hand it off for display.
	470
44a8e56a	471	=item B<-l> file name only
	472
	473	Display the file name of the module found.
	474
31bdbec1 GA	475	=item B<-f> perlfunc
	476
	477	The B<-f> option followed by the name of a perl built in function will
	478	extract the documentation of this function from L<perlfunc>.
	479
7eda7aea	480	=item B<PageName\|ModuleName\|ProgramName>
	481
	482	The item you want to look up. Nested modules (such as C<File::Basename>)
	483	are specified either as C<File::Basename> or C<File/Basename>. You may also
	484	give a descriptive name of a page, such as C<perlfunc>. You make also give a
	485	partial or wrong-case name, such as "basename" for "File::Basename", but
	486	this will be slower, if there is more then one page with the same partial
	487	name, you will only get the first one.
	488
	489	=back
	490
	491	=head1 ENVIRONMENT
	492
	493	Any switches in the C<PERLDOC> environment variable will be used before the
	494	command line arguments. C<perldoc> also searches directories
	495	specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
	496	defined) and C<PATH> environment variables.
	497	(The latter is so that embedded pods for executables, such as
	498	C<perldoc> itself, are available.)
	499
	500	=head1 AUTHOR
	501
	502	Kenneth Albanowski <kjahds@kjahds.com>
	503
	504	Minor updates by Andy Dougherty <doughera@lafcol.lafayette.edu>
	505
7eda7aea	506	=cut
	507
	508	#
137443ea	509	# Version 1.12: Sat Apr 12 22:41:09 EST 1997
	510	# Gurusamy Sarathy <gsar@umich.edu>
	511	# -various fixes for win32
7eda7aea	512	# Version 1.11: Tue Dec 26 09:54:33 EST 1995
	513	# Kenneth Albanowski <kjahds@kjahds.com>
	514	# -added Charles Bailey's further VMS patches, and -u switch
	515	# -added -t switch, with pod2text support
	516	#
	517	# Version 1.10: Thu Nov 9 07:23:47 EST 1995
	518	# Kenneth Albanowski <kjahds@kjahds.com>
	519	# -added VMS support
	520	# -added better error recognition (on no found pages, just exit. On
	521	# missing nroff/pod2man, just display raw pod.)
	522	# -added recursive/case-insensitive matching (thanks, Andreas). This
	523	# slows things down a bit, unfortunately. Give a precise name, and
	524	# it'll run faster.
	525	#
	526	# Version 1.01: Tue May 30 14:47:34 EDT 1995
	527	# Andy Dougherty <doughera@lafcol.lafayette.edu>
	528	# -added pod documentation.
	529	# -added PATH searching.
	530	# -added searching pod/ subdirectory (mainly to pick up perlfunc.pod
	531	# and friends.
	532	#
	533	#
	534	# TODO:
	535	#
	536	# Cache directories read during sloppy match
4633a7c4 LW	537	!NO!SUBS!
	538
	539	close OUT or die "Can't close $file: $!";
	540	chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
	541	exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';