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.
48 $me = $0; # Editing $0 is unportable
51 Usage: $me [-h] [-v] [-t] [-u] [-m] [-l] PageName|ModuleName|ProgramName
54 We suggest you use "perldoc perldoc" to get aquainted
62 $Is_VMS = $^O eq 'VMS';
63 $Is_MSWin32 = $^O eq 'MSWin32';
67 # Erase evidence of previous errors (if any), so exit status is simple.
70 perldoc [options] PageName|ModuleName|ProgramName...
71 perldoc [options] -f BuiltinFunction
74 -h Display this help message
75 -t Display pod using pod2text instead of pod2man and nroff
76 (-t is the default on win32)
77 -u Display unformatted pod text
78 -m Display modules file in its entirety
79 -l Display the modules file name
80 -v Verbosely describe what's going on
82 PageName|ModuleName...
83 is the name of a piece of documentation that you want to look at. You
84 may either give a descriptive name of the page (as in the case of
85 `perlfunc') the name of a module, either like `Term::Info',
86 `Term/Info', the partial name of a module, like `info', or
87 `makemaker', or the name of a program, like `perldoc'.
90 is the name of a perl function. Will extract documentation from
93 Any switches in the PERLDOC environment variable will be used before the
94 command line arguments.
102 unshift(@ARGV,shellwords($ENV{"PERLDOC"}));
104 getopts("mhtluvf:") || usage;
106 usage if $opt_h || $opt_h; # avoid -w warning
108 if ($opt_t + $opt_u + $opt_m + $opt_l > 1) {
109 usage("only one of -t, -u, -m or -l")
110 } elsif ($Is_MSWin32) {
111 $opt_t = 1 unless $opt_t + $opt_u + $opt_m + $opt_l;
114 if ($opt_t) { require Pod::Text; import Pod::Text; }
117 @pages = ("perlfunc");
140 # on a case-forgiving file system we can simply use -f $file
141 if ($Is_VMS or $Is_MSWin32 or $^O eq 'os2') {
142 return ( -f $file ) ? $file : '';
147 foreach $p (split(/\//, $file)){
150 } elsif (-f ("@p/$p")) {
156 while ($cip=readdir(DIR)) {
157 if (lc $cip eq $lcp){
163 return "" unless $found;
165 return "@p" if -f "@p";
168 return; # is not a file
172 my($recurse,$s,@dirs) = @_;
174 $s = VMS::Filespec::unixify($s) if $Is_VMS;
175 return $s if -f $s && containspod($s);
176 printf STDERR "looking for $s in @dirs\n" if $opt_v;
180 for ($i=0;$i<@dirs;$i++) {
182 ($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
183 if (( $ret = minus_f_nocase "$dir/$s.pod")
184 or ( $ret = minus_f_nocase "$dir/$s.pm" and containspod($ret))
185 or ( $ret = minus_f_nocase "$dir/$s" and containspod($ret))
187 $ret = minus_f_nocase "$dir/$s.com" and containspod($ret))
188 or ( $^O eq 'os2' and
189 $ret = minus_f_nocase "$dir/$s.cmd" and containspod($ret))
190 or ( ($Is_MSWin32 or $^O eq 'os2') and
191 $ret = minus_f_nocase "$dir/$s.bat" and containspod($ret))
192 or ( $ret = minus_f_nocase "$dir/pod/$s.pod")
193 or ( $ret = minus_f_nocase "$dir/pod/$s" and containspod($ret)))
198 my(@newdirs) = grep(-d,map("$dir/$_",grep(!/^\.\.?$/,readdir(D))));
200 @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
201 next unless @newdirs;
202 print STDERR "Also looking in @newdirs\n" if $opt_v;
203 push(@dirs,@newdirs);
211 print STDERR "Searching for $_\n" if $opt_v;
212 # We must look both in @INC for library modules and in PATH
213 # for executables, like h2xs or perldoc itself.
218 for ($i = 0; $trn = $ENV{'DCL$PATH'.$i}; $i++) {
219 push(@searchdirs,$trn);
222 push(@searchdirs, grep(-d, split($Config{path_sep},
225 @files= searchfor(0,$_,@searchdirs);
228 print STDERR "Found as @files\n" if $opt_v;
230 # no match, try recursive search
232 @searchdirs = grep(!/^\.$/,@INC);
235 @files= searchfor(1,$_,@searchdirs);
237 print STDERR "Loosely found as @files\n" if $opt_v;
239 print STDERR "No documentation found for '$_'\n";
246 exit ($Is_VMS ? 98962 : 1);
250 print join("\n", @found), "\n";
254 if( ! -t STDOUT ) { $no_tty = 1 }
257 $tmp = "$ENV{TEMP}\\perldoc1.$$";
258 push @pagers, qw( more< less notepad );
259 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
261 $tmp = 'Sys$Scratch:perldoc.tmp1_'.$$;
262 push @pagers, qw( most more less type/page );
266 $tmp = POSIX::tmpnam();
268 $tmp = "/tmp/perldoc1.$$";
270 push @pagers, qw( more less pg view cat );
271 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
273 unshift @pagers, $ENV{PERLDOC_PAGER} if $ENV{PERLDOC_PAGER};
276 foreach $pager (@pagers) {
277 system("$pager @found") or exit;
279 if ($Is_VMS) { eval 'use vmsish qw(status exit); exit $?' }
284 my $perlfunc = shift @found;
285 open(PFUNC, $perlfunc) or die "Can't open $perlfunc: $!";
289 last if /^=head2 Alphabetical Listing of Perl Functions/;
292 # Look for our function
295 if (/^=item\s+\Q$opt_f\E\b/o) {
300 push(@pod, $_) if $found;
304 open(FORMATTER, "| pod2text") || die "Can't start filter";
305 print FORMATTER "=over 8\n\n";
306 print FORMATTER @pod;
307 print FORMATTER "=back\n";
313 die "No documentation for perl function `$opt_f' found\n";
322 Pod::Text::pod2text($_,*TMP);
324 } elsif(not $opt_u) {
325 my $cmd = "pod2man --lax $_ | nroff -man";
326 $cmd .= " | col -x" if $^O =~ /hpux/;
328 unless(($err = $?)) {
335 if( $opt_u or $err or -z $tmp) {
340 $cut = $1 eq 'cut' if /^=(\w+)/;
354 foreach $pager (@pagers) {
355 system("$pager $tmp") or last;
359 1 while unlink($tmp); #Possibly pointless VMSism
367 perldoc - Look up Perl documentation in pod format.
371 B<perldoc> [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] PageName|ModuleName|ProgramName
373 B<perldoc> B<-f> BuiltinFunction
377 I<perldoc> looks up a piece of documentation in .pod format that is embedded
378 in the perl installation tree or in a perl script, and displays it via
379 C<pod2man | nroff -man | $PAGER>. (In addition, if running under HP-UX,
380 C<col -x> will be used.) This is primarily used for the documentation for
381 the perl library modules.
383 Your system may also have man pages installed for those modules, in
384 which case you can probably just use the man(1) command.
392 Prints out a brief help message.
396 Describes search for the item in detail.
398 =item B<-t> text output
400 Display docs using plain text converter, instead of nroff. This may be faster,
401 but it won't look as nice.
403 =item B<-u> unformatted
405 Find docs only; skip reformatting by pod2*
409 Display the entire module: both code and unformatted pod documentation.
410 This may be useful if the docs don't explain a function in the detail
411 you need, and you'd like to inspect the code directly; perldoc will find
412 the file for you and simply hand it off for display.
414 =item B<-l> file name only
416 Display the file name of the module found.
420 The B<-f> option followed by the name of a perl built in function will
421 extract the documentation of this function from L<perlfunc>.
423 =item B<PageName|ModuleName|ProgramName>
425 The item you want to look up. Nested modules (such as C<File::Basename>)
426 are specified either as C<File::Basename> or C<File/Basename>. You may also
427 give a descriptive name of a page, such as C<perlfunc>. You make also give a
428 partial or wrong-case name, such as "basename" for "File::Basename", but
429 this will be slower, if there is more then one page with the same partial
430 name, you will only get the first one.
436 Any switches in the C<PERLDOC> environment variable will be used before the
437 command line arguments. C<perldoc> also searches directories
438 specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
439 defined) and C<PATH> environment variables.
440 (The latter is so that embedded pods for executables, such as
441 C<perldoc> itself, are available.)
445 Kenneth Albanowski <kjahds@kjahds.com>
447 Minor updates by Andy Dougherty <doughera@lafcol.lafayette.edu>
452 # Version 1.12: Sat Apr 12 22:41:09 EST 1997
453 # Gurusamy Sarathy <gsar@umich.edu>
454 # -various fixes for win32
455 # Version 1.11: Tue Dec 26 09:54:33 EST 1995
456 # Kenneth Albanowski <kjahds@kjahds.com>
457 # -added Charles Bailey's further VMS patches, and -u switch
458 # -added -t switch, with pod2text support
460 # Version 1.10: Thu Nov 9 07:23:47 EST 1995
461 # Kenneth Albanowski <kjahds@kjahds.com>
463 # -added better error recognition (on no found pages, just exit. On
464 # missing nroff/pod2man, just display raw pod.)
465 # -added recursive/case-insensitive matching (thanks, Andreas). This
466 # slows things down a bit, unfortunately. Give a precise name, and
469 # Version 1.01: Tue May 30 14:47:34 EDT 1995
470 # Andy Dougherty <doughera@lafcol.lafayette.edu>
471 # -added pod documentation.
472 # -added PATH searching.
473 # -added searching pod/ subdirectory (mainly to pick up perlfunc.pod
479 # Cache directories read during sloppy match
482 close OUT or die "Can't close $file: $!";
483 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
484 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';