[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)) =~ s/\.PL$//;
$file =~ s/\.pl$//
	if ($^O eq 'VMS' or $^O eq 'os2');  # "case-forgiving"

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 perl -S \$0 "\$@"'
	if 0;
!GROK!THIS!

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

print OUT <<'!NO!SUBS!';
    eval 'exec perl -S $0 "$@"'
	if 0;

#
# 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) {
	die <<EOF;
Usage: $0 [-h] [-v] [-t] [-u] [-m] PageName|ModuleName|ProgramName

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

use Getopt::Std;
$Is_VMS = $^O eq 'VMS';

sub usage{
        warn "@_\n" if @_;
    die <<EOF;
perldoc [-h] [-v] [-u] PageName|ModuleName|ProgramName...
    -h   Display this help message.
    -t   Display pod using pod2text instead of pod2man and nroff.
    -u	 Display unformatted pod text
    -m   Display modules file in its entirety
    -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'.
         
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("mhtuv") || usage;

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

usage("only one of -t, -u, or -m") if $opt_t + $opt_u + $opt_m > 1;

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

@pages = @ARGV;

sub containspod {
	my($file) = @_;
	local($_);
	open(TEST,"<$file");
	while(<TEST>) {
		if(/^=head/) {
			close(TEST);
			return 1;
		}
	}
	close(TEST);
	return 0;
}

 sub minus_f_nocase {
     my($file) = @_;
     local *DIR;
     local($")="/";
     my(@p,$p,$cip);
     foreach $p (split(/\//, $file)){
	if ($Is_VMS and not scalar @p) {
	    # VMS filesystems don't begin at '/'
	    push(@p,$p);
	    next;
	}
 	if (-d ("@p/$p")){
 	    push @p, $p;
 	} elsif (-f ("@p/$p")) {
 	    return "@p/$p";
 	} else {
 	    my $found=0;
 	    my $lcp = lc $p;
 	    opendir DIR, "@p";
 	    while ($cip=readdir(DIR)) {
		$cip =~ s/\.dir$// if $Is_VMS;
 		if (lc $cip eq $lcp){
 		    $found++;
 		    last;
 		}
 	    }
 	    closedir DIR;
 	    return "" unless $found;
 	    push @p, $cip;
 	    return "@p" if -f "@p";
 	}
     }
     return; # is not a file
 }
 
  sub searchfor {
  	my($recurse,$s,@dirs) = @_;
  	$s =~ s!::!/!g;
  	$s = VMS::Filespec::unixify($s) if $Is_VMS;
  	printf STDERR "looking for $s in @dirs\n" if $opt_v;
 	my $ret;
 	my $i;
 	my $dir;
  	for ($i=0;$i<@dirs;$i++) {
  		$dir = $dirs[$i];
  		($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
 	    if ((    $ret = minus_f_nocase "$dir/$s.pod")
 		or ( $ret = minus_f_nocase "$dir/$s.pm"  and containspod($ret))
 		or ( $ret = minus_f_nocase "$dir/$s"     and containspod($ret))
 		or ( $Is_VMS and 
 		     $ret = minus_f_nocase "$dir/$s.com" and containspod($ret))
 		or ( $ret = minus_f_nocase "$dir/pod/$s.pod")
 		or ( $ret = minus_f_nocase "$dir/pod/$s" and containspod($ret)))
 		{ return $ret; }
 		
 		if($recurse) {
			opendir(D,$dir);
			my(@newdirs) = grep(-d,map("$dir/$_",grep(!/^\.\.?$/,readdir(D))));
			closedir(D);
			@newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
			next unless @newdirs;
			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(':', $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";
		}
	}
	push(@found,@files);
}

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

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

unless($Is_VMS) {
	$tmp = "/tmp/perldoc1.$$";
	$goodresult = 0;
	@pagers = qw( more less pg view cat );
	unshift(@pagers,$ENV{PAGER}) if $ENV{PAGER};
} else {
	$tmp = 'Sys$Scratch:perldoc.tmp1_'.$$;
	@pagers = qw( most more less type/page );
	unshift(@pagers,$ENV{PERLDOC_PAGER}) if $ENV{PERLDOC_PAGER};
	$goodresult = 1;
}

if ($opt_m) {
    foreach $pager (@pagers) {
	my($sts) = system("$pager @found");
	exit 0 if ($Is_VMS ? ($sts & 1) : !$sts);
    }
    exit $Is_VMS ? $sts : 1;
} 

foreach (@found) {

	if($opt_t) {
		open(TMP,">>$tmp");
		Pod::Text::pod2text($_,*TMP);
		close(TMP);
	} elsif(not $opt_u) {
		open(TMP,">>$tmp");
		if($^O =~ /hpux/) {
			$rslt = `pod2man $_ | nroff -man | col -x`;
		} else {
			$rslt = `pod2man $_ | nroff -man`;
		}
		if ($Is_VMS) { $err = !($? % 2) || $rslt =~ /IVVERB/; }
		else      { $err = $?; }
		print TMP $rslt unless $err;
		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( $opt_f ) {
	open(TMP,"<$tmp");
	print while <TMP>;
	close(TMP);
} else {
	foreach $pager (@pagers) {
		$sts = system("$pager $tmp");
		last if $Is_VMS && ($sts & 1);
		last unless $sts;
	}
}

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>] PageName|ModuleName|ProgramName

=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<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>

=head1 SEE ALSO

=head1 DIAGNOSTICS

=cut

#
# 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.
	15	chdir(dirname($0));
	16	($file = basename($0)) =~ s/\.PL$//;
	17	$file =~ s/\.pl$//
7eda7aea	18	if ($^O eq 'VMS' or $^O eq 'os2'); # "case-forgiving"
4633a7c4 LW	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
85880f03	27	print OUT <<"!GROK!THIS!";
4633a7c4 LW	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!';
85880f03	36	eval 'exec perl -S $0 "$@"'
85880f03	37	if 0;
4633a7c4 LW	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
	47	if(@ARGV<1) {
	48	die <<EOF;
7eda7aea	49	Usage: $0 [-h] [-v] [-t] [-u] [-m] PageName\|ModuleName\|ProgramName
4633a7c4 LW	50
	51	We suggest you use "perldoc perldoc" to get aquainted
	52	with the system.
	53	EOF
	54	}
	55
	56	use Getopt::Std;
7eda7aea	57	$Is_VMS = $^O eq 'VMS';
4633a7c4 LW	58
	59	sub usage{
	60	warn "@_\n" if @_;
	61	die <<EOF;
85880f03	62	perldoc [-h] [-v] [-u] PageName\|ModuleName\|ProgramName...
4633a7c4	63	-h Display this help message.
85880f03	64	-t Display pod using pod2text instead of pod2man and nroff.
85880f03	65	-u Display unformatted pod text
7eda7aea	66	-m Display modules file in its entirety
4633a7c4 LW	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
7eda7aea	86	getopts("mhtuv") \|\| usage;
85880f03	87
85880f03	88	usage if $opt_h \|\| $opt_h; # avoid -w warning
4633a7c4	89
7eda7aea	90	usage("only one of -t, -u, or -m") if $opt_t + $opt_u + $opt_m > 1;
4633a7c4	91
7eda7aea	92	if ($opt_t) { require Pod::Text; import Pod::Text; }
4633a7c4	93
7eda7aea	94	@pages = @ARGV;
85880f03	95
4633a7c4 LW	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)){
85880f03	116	if ($Is_VMS and not scalar @p) {
	117	# VMS filesystems don't begin at '/'
	118	push(@p,$p);
	119	next;
	120	}
4633a7c4 LW	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)) {
85880f03	130	$cip =~ s/\.dir$// if $Is_VMS;
4633a7c4 LW	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;
85880f03	148	$s = VMS::Filespec::unixify($s) if $Is_VMS;
4633a7c4 LW	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];
85880f03	155	($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
4633a7c4 LW	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))
85880f03	159	or ( $Is_VMS and
85880f03	160	$ret = minus_f_nocase "$dir/$s.com" and containspod($ret))
4633a7c4 LW	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);
85880f03	169	@newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
7eda7aea	170	next unless @newdirs;
4633a7c4 LW	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;
7eda7aea	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);
85880f03	194	}
4633a7c4 LW	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 ) {
85880f03	205	print STDERR "Loosely found as @files\n" if $opt_v;
4633a7c4 LW	206	} else {
	207	print STDERR "No documentation found for '$_'\n";
	208	}
	209	}
	210	push(@found,@files);
	211	}
	212
	213	if(!@found) {
85880f03	214	exit ($Is_VMS ? 98962 : 1);
4633a7c4 LW	215	}
4633a7c4 LW	216
4633a7c4 LW	217	if( ! -t STDOUT ) { $opt_f = 1 }
4633a7c4 LW	218
85880f03	219	unless($Is_VMS) {
4633a7c4	220	$tmp = "/tmp/perldoc1.$$";
4633a7c4	221	$goodresult = 0;
85880f03	222	@pagers = qw( more less pg view cat );
85880f03	223	unshift(@pagers,$ENV{PAGER}) if $ENV{PAGER};
4633a7c4 LW	224	} else {
4633a7c4 LW	225	$tmp = 'Sys$Scratch:perldoc.tmp1_'.$$;
85880f03	226	@pagers = qw( most more less type/page );
85880f03	227	unshift(@pagers,$ENV{PERLDOC_PAGER}) if $ENV{PERLDOC_PAGER};
4633a7c4 LW	228	$goodresult = 1;
	229	}
	230
7eda7aea	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
4633a7c4	239	foreach (@found) {
7eda7aea	240
85880f03	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");
40fc7247	247	if($^O =~ /hpux/) {
	248	$rslt = `pod2man $_ \| nroff -man \| col -x`;
	249	} else {
	250	$rslt = `pod2man $_ \| nroff -man`;
	251	}
85880f03	252	if ($Is_VMS) { $err = !($? % 2) \|\| $rslt =~ /IVVERB/; }
	253	else { $err = $?; }
	254	print TMP $rslt unless $err;
	255	close TMP;
	256	}
4633a7c4	257
85880f03	258	if( $opt_u or $err or -z $tmp) {
4633a7c4 LW	259	open(OUT,">>$tmp");
4633a7c4 LW	260	open(IN,"<$_");
85880f03	261	$cut = 1;
	262	while (<IN>) {
	263	$cut = $1 eq 'cut' if /^=(\w+)/;
	264	next if $cut;
	265	print OUT;
	266	}
4633a7c4 LW	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 {
85880f03	277	foreach $pager (@pagers) {
	278	$sts = system("$pager $tmp");
	279	last if $Is_VMS && ($sts & 1);
	280	last unless $sts;
4633a7c4 LW	281	}
	282	}
	283
	284	1 while unlink($tmp); #Possibly pointless VMSism
	285
	286	exit 0;
7eda7aea	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
40fc7247	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.
7eda7aea	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
4633a7c4 LW	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 ':';