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] [-F] PageName|ModuleName|ProgramName
54 We suggest you use "perldoc perldoc" to get aquainted
65 $Is_VMS = $^O eq 'VMS';
66 $Is_MSWin32 = $^O eq 'MSWin32';
67 $Is_Dos = $^O eq 'dos';
71 # Erase evidence of previous errors (if any), so exit status is simple.
74 perldoc [options] PageName|ModuleName|ProgramName...
75 perldoc [options] -f BuiltinFunction
78 -h Display this help message
79 -t Display pod using pod2text instead of pod2man and nroff
80 (-t is the default on win32)
81 -u Display unformatted pod text
82 -m Display modules file in its entirety
83 -l Display the modules file name
84 -F Arguments are file names, not modules
85 -v Verbosely describe what's going on
87 PageName|ModuleName...
88 is the name of a piece of documentation that you want to look at. You
89 may either give a descriptive name of the page (as in the case of
90 `perlfunc') the name of a module, either like `Term::Info',
91 `Term/Info', the partial name of a module, like `info', or
92 `makemaker', or the name of a program, like `perldoc'.
95 is the name of a perl function. Will extract documentation from
98 Any switches in the PERLDOC environment variable will be used before the
99 command line arguments.
104 use Text::ParseWords;
107 unshift(@ARGV,shellwords($ENV{"PERLDOC"}));
109 getopts("mhtluvFf:") || usage;
111 usage if $opt_h || $opt_h; # avoid -w warning
113 if ($opt_t + $opt_u + $opt_m + $opt_l > 1) {
114 usage("only one of -t, -u, -m or -l")
115 } elsif ($Is_MSWin32 || $Is_Dos) {
116 $opt_t = 1 unless $opt_t + $opt_u + $opt_m + $opt_l;
119 if ($opt_t) { require Pod::Text; import Pod::Text; }
122 @pages = ("perlfunc");
127 # Does this look like a module or extension directory?
128 if (-f "Makefile.PL") {
129 # Add ., lib and blib/* libs to @INC (if they exist)
131 unshift(@INC, 'lib') if -d 'lib';
132 require ExtUtils::testlib;
138 my($file, $readit) = @_;
139 return 1 if !$readit && $file =~ /\.pod$/i;
154 # on a case-forgiving file system we can simply use -f $file
155 if ($Is_VMS or $Is_MSWin32 or $Is_Dos or $^O eq 'os2') {
156 return $file if -f $file and -r _;
157 warn "Ignored $file: unreadable\n" if -f _;
163 foreach $p (split(/\//, $file)){
168 if ( $p eq $global_target) {
169 $tmp_path = join ('/', @p);
171 for (@global_found) {
172 $path_f = 1 if $_ eq $tmp_path;
174 push (@global_found, $tmp_path) unless $path_f;
175 print STDERR "Found as @p but directory\n" if $opt_v;
177 } elsif (-f _ && -r _) {
180 warn "Ignored $try: unreadable\n";
185 while ($cip=readdir(DIR)) {
186 if (lc $cip eq $lcp){
192 return "" unless $found;
194 return "@p" if -f "@p" and -r _;
195 warn "Ignored $file: unreadable\n" if -f _;
198 return; # is not a file
204 return minus_f_nocase($file) && containspod($file) ? $file : "";
209 my($recurse,$s,@dirs) = @_;
211 $s = VMS::Filespec::unixify($s) if $Is_VMS;
212 return $s if -f $s && containspod($s);
213 printf STDERR "Looking for $s in @dirs\n" if $opt_v;
217 $global_target = (split('/', $s))[-1];
218 for ($i=0; $i<@dirs; $i++) {
220 ($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
221 if ( ( $ret = check_file "$dir/$s.pod")
222 or ( $ret = check_file "$dir/$s.pm")
223 or ( $ret = check_file "$dir/$s")
225 $ret = check_file "$dir/$s.com")
226 or ( $^O eq 'os2' and
227 $ret = check_file "$dir/$s.cmd")
228 or ( ($Is_MSWin32 or $Is_Dos or $^O eq 'os2') and
229 $ret = check_file "$dir/$s.bat")
230 or ( $ret = check_file "$dir/pod/$s.pod")
231 or ( $ret = check_file "$dir/pod/$s")
238 my @newdirs = map "$dir/$_", grep {
240 not /^auto$/ and # save time! don't search auto dirs
244 next unless @newdirs;
245 @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
246 print STDERR "Also looking in @newdirs\n" if $opt_v;
247 push(@dirs,@newdirs);
255 print STDERR "Searching for $_\n" if $opt_v;
256 # We must look both in @INC for library modules and in PATH
257 # for executables, like h2xs or perldoc itself.
261 push @found, $_ if $opt_m or containspod($_);
267 for ($i = 0; $trn = $ENV{'DCL$PATH'.$i}; $i++) {
268 push(@searchdirs,$trn);
271 push(@searchdirs, grep(-d, split($Config{path_sep},
274 @files= searchfor(0,$_,@searchdirs);
277 print STDERR "Found as @files\n" if $opt_v;
279 # no match, try recursive search
281 @searchdirs = grep(!/^\.$/,@INC);
283 @files= searchfor(1,$_,@searchdirs);
285 print STDERR "Loosely found as @files\n" if $opt_v;
287 print STDERR "No documentation found for \"$_\".\n";
289 print STDERR "However, try\n";
290 my $dir = $file = "";
291 for $dir (@global_found) {
292 opendir(DIR, $dir) or die "$!";
293 while ($file = readdir(DIR)) {
294 next if ($file =~ /^\./);
295 $file =~ s/\.(pm|pod)$//;
296 print STDERR "\tperldoc $_\::$file\n";
307 exit ($Is_VMS ? 98962 : 1);
311 print join("\n", @found), "\n";
315 if( ! -t STDOUT ) { $no_tty = 1 }
318 $tmp = "$ENV{TEMP}\\perldoc1.$$";
319 push @pagers, qw( more< less notepad );
320 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
322 $tmp = 'Sys$Scratch:perldoc.tmp1_'.$$;
323 push @pagers, qw( most more less type/page );
325 $tmp = "$ENV{TEMP}/perldoc1.$$";
327 push @pagers, qw( less.exe more.com< );
328 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
332 $tmp = POSIX::tmpnam();
334 $tmp = "/tmp/perldoc1.$$";
336 push @pagers, qw( more less pg view cat );
337 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
339 unshift @pagers, $ENV{PERLDOC_PAGER} if $ENV{PERLDOC_PAGER};
342 foreach $pager (@pagers) {
343 system("$pager @found") or exit;
345 if ($Is_VMS) { eval 'use vmsish qw(status exit); exit $?' }
350 my $perlfunc = shift @found;
351 open(PFUNC, $perlfunc) or die "Can't open $perlfunc: $!";
355 last if /^=head2 Alphabetical Listing of Perl Functions/;
358 # Look for our function
362 if (/^=item\s+\Q$opt_f\E\b/o) {
369 ++$found if /^\w/; # found descriptive text
373 open(FORMATTER, "| pod2text") || die "Can't start filter";
374 print FORMATTER "=over 8\n\n";
375 print FORMATTER @pod;
376 print FORMATTER "=back\n";
382 die "No documentation for perl function `$opt_f' found\n";
391 Pod::Text::pod2text($_,*TMP);
393 } elsif(not $opt_u) {
394 my $cmd = "pod2man --lax $_ | nroff -man";
395 $cmd .= " | col -x" if $^O =~ /hpux/;
397 unless(($err = $?)) {
404 if( $opt_u or $err or -z $tmp) {
409 $cut = $1 eq 'cut' if /^=(\w+)/;
423 foreach $pager (@pagers) {
424 system("$pager $tmp") or last;
428 1 while unlink($tmp); #Possibly pointless VMSism
436 perldoc - Look up Perl documentation in pod format.
440 B<perldoc> [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] PageName|ModuleName|ProgramName
442 B<perldoc> B<-f> BuiltinFunction
446 I<perldoc> looks up a piece of documentation in .pod format that is embedded
447 in the perl installation tree or in a perl script, and displays it via
448 C<pod2man | nroff -man | $PAGER>. (In addition, if running under HP-UX,
449 C<col -x> will be used.) This is primarily used for the documentation for
450 the perl library modules.
452 Your system may also have man pages installed for those modules, in
453 which case you can probably just use the man(1) command.
461 Prints out a brief help message.
465 Describes search for the item in detail.
467 =item B<-t> text output
469 Display docs using plain text converter, instead of nroff. This may be faster,
470 but it won't look as nice.
472 =item B<-u> unformatted
474 Find docs only; skip reformatting by pod2*
478 Display the entire module: both code and unformatted pod documentation.
479 This may be useful if the docs don't explain a function in the detail
480 you need, and you'd like to inspect the code directly; perldoc will find
481 the file for you and simply hand it off for display.
483 =item B<-l> file name only
485 Display the file name of the module found.
487 =item B<-F> file names
489 Consider arguments as file names, no search in directories should be performed.
493 The B<-f> option followed by the name of a perl built in function will
494 extract the documentation of this function from L<perlfunc>.
496 =item B<PageName|ModuleName|ProgramName>
498 The item you want to look up. Nested modules (such as C<File::Basename>)
499 are specified either as C<File::Basename> or C<File/Basename>. You may also
500 give a descriptive name of a page, such as C<perlfunc>. You make also give a
501 partial or wrong-case name, such as "basename" for "File::Basename", but
502 this will be slower, if there is more then one page with the same partial
503 name, you will only get the first one.
509 Any switches in the C<PERLDOC> environment variable will be used before the
510 command line arguments. C<perldoc> also searches directories
511 specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
512 defined) and C<PATH> environment variables.
513 (The latter is so that embedded pods for executables, such as
514 C<perldoc> itself, are available.)
518 Kenneth Albanowski <kjahds@kjahds.com>
520 Minor updates by Andy Dougherty <doughera@lafcol.lafayette.edu>
525 # Version 1.12: Sat Apr 12 22:41:09 EST 1997
526 # Gurusamy Sarathy <gsar@umich.edu>
527 # -various fixes for win32
528 # Version 1.11: Tue Dec 26 09:54:33 EST 1995
529 # Kenneth Albanowski <kjahds@kjahds.com>
530 # -added Charles Bailey's further VMS patches, and -u switch
531 # -added -t switch, with pod2text support
533 # Version 1.10: Thu Nov 9 07:23:47 EST 1995
534 # Kenneth Albanowski <kjahds@kjahds.com>
536 # -added better error recognition (on no found pages, just exit. On
537 # missing nroff/pod2man, just display raw pod.)
538 # -added recursive/case-insensitive matching (thanks, Andreas). This
539 # slows things down a bit, unfortunately. Give a precise name, and
542 # Version 1.01: Tue May 30 14:47:34 EDT 1995
543 # Andy Dougherty <doughera@lafcol.lafayette.edu>
544 # -added pod documentation.
545 # -added PATH searching.
546 # -added searching pod/ subdirectory (mainly to pick up perlfunc.pod
552 # Cache directories read during sloppy match
555 close OUT or die "Can't close $file: $!";
556 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
557 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';