4 use File::Basename qw(&basename &dirname);
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
11 # to ensure Configure will look for $Config{startperl}.
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.
16 $file = basename($0, '.PL');
17 $file .= '.com' if $^O eq 'VMS';
19 open OUT,">$file" or die "Can't create $file: $!";
21 print "Extracting $file (with variable substitutions)\n";
23 # In this section, perl variables will be expanded during extraction.
24 # You can use $Config{...} to use Configure variables.
26 print OUT <<"!GROK!THIS!";
28 eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
29 if \$running_under_some_shell;
32 push \@pagers, "$Config{'pager'}" if -x "$Config{'pager'}";
35 # In the following, perl variables are not expanded during extraction.
37 print OUT <<'!NO!SUBS!';
40 # Perldoc revision #1 -- look up a piece of documentation in .pod format that
41 # is embedded in the perl installation tree.
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.
50 Usage: $0 [-h] [-v] [-t] [-u] [-m] [-l] PageName|ModuleName|ProgramName
53 We suggest you use "perldoc perldoc" to get aquainted
59 $Is_VMS = $^O eq 'VMS';
63 # Erase evidence of previous errors (if any), so exit status is simple.
66 perldoc [options] PageName|ModuleName|ProgramName...
67 perldoc [options] -f BuiltinFunction
70 -h Display this help message.
71 -t Display pod using pod2text instead of pod2man and nroff.
72 -u Display unformatted pod text
73 -m Display modules file in its entirety
74 -l Display the modules file name
75 -v Verbosely describe what's going on.
77 PageName|ModuleName...
78 is the name of a piece of documentation that you want to look at. You
79 may either give a descriptive name of the page (as in the case of
80 `perlfunc') the name of a module, either like `Term::Info',
81 `Term/Info', the partial name of a module, like `info', or
82 `makemaker', or the name of a program, like `perldoc'.
85 is the name of a perl function. Will extract documentation from
88 Any switches in the PERLDOC environment variable will be used before the
89 command line arguments.
97 unshift(@ARGV,shellwords($ENV{"PERLDOC"}));
99 getopts("mhtluvf:") || usage;
101 usage if $opt_h || $opt_h; # avoid -w warning
103 usage("only one of -t, -u, -m or -l") if $opt_t + $opt_u + $opt_m + $opt_l > 1;
105 if ($opt_t) { require Pod::Text; import Pod::Text; }
108 @pages = ("perlfunc");
134 foreach $p (split(/\//, $file)){
135 if (($Is_VMS or $^O eq 'os2') and not scalar @p) {
136 # VMSish filesystems don't begin at '/'
142 } elsif (-f ("@p/$p")) {
148 while ($cip=readdir(DIR)) {
149 $cip =~ s/\.dir$// if $Is_VMS;
150 if (lc $cip eq $lcp){
156 return "" unless $found;
158 return "@p" if -f "@p";
161 return; # is not a file
165 my($recurse,$s,@dirs) = @_;
167 $s = VMS::Filespec::unixify($s) if $Is_VMS;
168 return $s if -f $s && containspod($s);
169 printf STDERR "looking for $s in @dirs\n" if $opt_v;
173 for ($i=0;$i<@dirs;$i++) {
175 ($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
176 if (( $ret = minus_f_nocase "$dir/$s.pod")
177 or ( $ret = minus_f_nocase "$dir/$s.pm" and containspod($ret))
178 or ( $ret = minus_f_nocase "$dir/$s" and containspod($ret))
180 $ret = minus_f_nocase "$dir/$s.com" and containspod($ret))
181 or ( $ret = minus_f_nocase "$dir/pod/$s.pod")
182 or ( $ret = minus_f_nocase "$dir/pod/$s" and containspod($ret)))
187 my(@newdirs) = grep(-d,map("$dir/$_",grep(!/^\.\.?$/,readdir(D))));
189 @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
190 next unless @newdirs;
191 print STDERR "Also looking in @newdirs\n" if $opt_v;
192 push(@dirs,@newdirs);
200 print STDERR "Searching for $_\n" if $opt_v;
201 # We must look both in @INC for library modules and in PATH
202 # for executables, like h2xs or perldoc itself.
207 for ($i = 0; $trn = $ENV{'DCL$PATH'.$i}; $i++) {
208 push(@searchdirs,$trn);
211 push(@searchdirs, grep(-d, split(':', $ENV{'PATH'})));
213 @files= searchfor(0,$_,@searchdirs);
216 print STDERR "Found as @files\n" if $opt_v;
218 # no match, try recursive search
220 @searchdirs = grep(!/^\.$/,@INC);
223 @files= searchfor(1,$_,@searchdirs);
225 print STDERR "Loosely found as @files\n" if $opt_v;
227 print STDERR "No documentation found for '$_'\n";
234 exit ($Is_VMS ? 98962 : 1);
238 print join("\n", @found), "\n";
242 if( ! -t STDOUT ) { $no_tty = 1 }
245 $tmp = "/tmp/perldoc1.$$";
246 push @pagers, qw( more less pg view cat );
247 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
249 $tmp = 'Sys$Scratch:perldoc.tmp1_'.$$;
250 push @pagers, qw( most more less type/page );
252 unshift @pagers, $ENV{PERLDOC_PAGER} if $ENV{PERLDOC_PAGER};
255 foreach $pager (@pagers) {
256 system("$pager @found") or exit;
258 if ($Is_VMS) { eval 'use vmsish qw(status exit); exit $?' }
263 my $perlfunc = shift @found;
264 open(PFUNC, $perlfunc) or die "Can't open $perlfunc: $!";
268 last if /^=head2 Alphabetical Listing of Perl Functions/;
271 # Look for our function
274 if (/^=item\s+\Q$opt_f\E\b/o) {
279 push(@pod, $_) if $found;
283 open(FORMATTER, "| pod2text") || die "Can't start filter";
284 print FORMATTER "=over 8\n\n";
285 print FORMATTER @pod;
286 print FORMATTER "=back\n";
292 die "No documentation for perl function `$func' found\n";
301 Pod::Text::pod2text($_,*TMP);
303 } elsif(not $opt_u) {
304 my $cmd = "pod2man --lax $_ | nroff -man";
305 $cmd .= " | col -x" if $^O =~ /hpux/;
307 unless(($err = $?)) {
314 if( $opt_u or $err or -z $tmp) {
319 $cut = $1 eq 'cut' if /^=(\w+)/;
333 foreach $pager (@pagers) {
334 system("$pager $tmp") or last;
338 1 while unlink($tmp); #Possibly pointless VMSism
346 perldoc - Look up Perl documentation in pod format.
350 B<perldoc> [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] PageName|ModuleName|ProgramName
352 B<perldoc> B<-f> BuiltinFunction
356 I<perldoc> looks up a piece of documentation in .pod format that is embedded
357 in the perl installation tree or in a perl script, and displays it via
358 C<pod2man | nroff -man | $PAGER>. (In addition, if running under HP-UX,
359 C<col -x> will be used.) This is primarily used for the documentation for
360 the perl library modules.
362 Your system may also have man pages installed for those modules, in
363 which case you can probably just use the man(1) command.
371 Prints out a brief help message.
375 Describes search for the item in detail.
377 =item B<-t> text output
379 Display docs using plain text converter, instead of nroff. This may be faster,
380 but it won't look as nice.
382 =item B<-u> unformatted
384 Find docs only; skip reformatting by pod2*
388 Display the entire module: both code and unformatted pod documentation.
389 This may be useful if the docs don't explain a function in the detail
390 you need, and you'd like to inspect the code directly; perldoc will find
391 the file for you and simply hand it off for display.
393 =item B<-l> file name only
395 Display the file name of the module found.
399 The B<-f> option followed by the name of a perl built in function will
400 extract the documentation of this function from L<perlfunc>.
402 =item B<PageName|ModuleName|ProgramName>
404 The item you want to look up. Nested modules (such as C<File::Basename>)
405 are specified either as C<File::Basename> or C<File/Basename>. You may also
406 give a descriptive name of a page, such as C<perlfunc>. You make also give a
407 partial or wrong-case name, such as "basename" for "File::Basename", but
408 this will be slower, if there is more then one page with the same partial
409 name, you will only get the first one.
415 Any switches in the C<PERLDOC> environment variable will be used before the
416 command line arguments. C<perldoc> also searches directories
417 specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
418 defined) and C<PATH> environment variables.
419 (The latter is so that embedded pods for executables, such as
420 C<perldoc> itself, are available.)
424 Kenneth Albanowski <kjahds@kjahds.com>
426 Minor updates by Andy Dougherty <doughera@lafcol.lafayette.edu>
431 # Version 1.11: Tue Dec 26 09:54:33 EST 1995
432 # Kenneth Albanowski <kjahds@kjahds.com>
433 # -added Charles Bailey's further VMS patches, and -u switch
434 # -added -t switch, with pod2text support
436 # Version 1.10: Thu Nov 9 07:23:47 EST 1995
437 # Kenneth Albanowski <kjahds@kjahds.com>
439 # -added better error recognition (on no found pages, just exit. On
440 # missing nroff/pod2man, just display raw pod.)
441 # -added recursive/case-insensitive matching (thanks, Andreas). This
442 # slows things down a bit, unfortunately. Give a precise name, and
445 # Version 1.01: Tue May 30 14:47:34 EDT 1995
446 # Andy Dougherty <doughera@lafcol.lafayette.edu>
447 # -added pod documentation.
448 # -added PATH searching.
449 # -added searching pod/ subdirectory (mainly to pick up perlfunc.pod
455 # Cache directories read during sloppy match
458 close OUT or die "Can't close $file: $!";
459 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
460 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';