4 use File::Basename qw(&basename &dirname);
7 # List explicitly here the variables you want Configure to
8 # generate. Metaconfig only looks for shell variables, so you
9 # have to mention them as if they were shell variables, not
10 # %Config entries. Thus you write
12 # to ensure Configure will look for $Config{startperl}.
14 # This forces PL files to create target in same directory as PL file.
15 # This is so that make depend always knows where to find PL derivatives.
18 $file = basename($0, '.PL');
19 $file .= '.com' if $^O eq 'VMS';
21 open OUT,">$file" or die "Can't create $file: $!";
23 print "Extracting $file (with variable substitutions)\n";
25 # In this section, perl variables will be expanded during extraction.
26 # You can use $Config{...} to use Configure variables.
28 print OUT <<"!GROK!THIS!";
30 eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
35 push \@pagers, "$Config{'pager'}" if -x "$Config{'pager'}";
38 # In the following, perl variables are not expanded during extraction.
40 print OUT <<'!NO!SUBS!';
43 # Perldoc revision #1 -- look up a piece of documentation in .pod format that
44 # is embedded in the perl installation tree.
46 # This is not to be confused with Tom Christianson's perlman, which is a
47 # man replacement, written in perl. This perldoc is strictly for reading
48 # the perl manuals, though it too is written in perl.
51 my $me = $0; # Editing $0 is unportable
54 Usage: $me [-h] [-r] [-i] [-v] [-t] [-u] [-m] [-l] [-F] [-X] PageName|ModuleName|ProgramName
58 The -h option prints more help. Also try "perldoc perldoc" to get
59 aquainted with the system.
66 my @global_found = ();
67 my $global_target = "";
69 my $Is_VMS = $^O eq 'VMS';
70 my $Is_MSWin32 = $^O eq 'MSWin32';
71 my $Is_Dos = $^O eq 'dos';
75 # Erase evidence of previous errors (if any), so exit status is simple.
78 perldoc [options] PageName|ModuleName|ProgramName...
79 perldoc [options] -f BuiltinFunction
80 perldoc [options] -q FAQRegex
83 -h Display this help message
84 -r Recursive search (slow)
86 -t Display pod using pod2text instead of pod2man and nroff
87 (-t is the default on win32)
88 -u Display unformatted pod text
89 -m Display module's file in its entirety
90 -l Display the module's file name
91 -F Arguments are file names, not modules
92 -v Verbosely describe what's going on
93 -X use index if present (looks for pod.idx at $Config{archlib})
94 -q Search the text of questions (not answers) in perlfaq[1-9]
96 PageName|ModuleName...
97 is the name of a piece of documentation that you want to look at. You
98 may either give a descriptive name of the page (as in the case of
99 `perlfunc') the name of a module, either like `Term::Info',
100 `Term/Info', the partial name of a module, like `info', or
101 `makemaker', or the name of a program, like `perldoc'.
104 is the name of a perl function. Will extract documentation from
108 is a regex. Will search perlfaq[1-9] for and extract any
109 questions that match.
111 Any switches in the PERLDOC environment variable will be used before the
112 command line arguments. The optional pod index file contains a list of
113 filenames, one per line.
118 if (defined $ENV{"PERLDOC"}) {
119 require Text::ParseWords;
120 unshift(@ARGV, Text::ParseWords::shellwords($ENV{"PERLDOC"}));
124 my $getopts = "mhtluvriFf:Xq:";
125 print OUT <<"!GET!OPTS!";
127 use vars qw( @{[map "\$opt_$_", ($getopts =~ /\w/g)]} );
129 getopts("$getopts") || usage;
132 print OUT <<'!NO!SUBS!';
138 $podidx = "$Config{'archlib'}/pod.idx";
139 $podidx = "" unless -f $podidx && -r _ && -M _ <= 7;
142 if ((my $opts = do{ local $^W; $opt_t + $opt_u + $opt_m + $opt_l }) > 1) {
143 usage("only one of -t, -u, -m or -l")
147 || !(exists $ENV{TERM} && $ENV{TERM} !~ /dumb|emacs|none|unknown/i))
149 $opt_t = 1 unless $opts
152 if ($opt_t) { require Pod::Text; import Pod::Text; }
156 @pages = ("perlfunc");
159 @pages = ("perlfaq1" .. "perlfaq9");
165 # Does this look like a module or extension directory?
166 if (-f "Makefile.PL") {
167 # Add ., lib and blib/* libs to @INC (if they exist)
169 unshift(@INC, 'lib') if -d 'lib';
170 require ExtUtils::testlib;
174 my($file, $readit) = @_;
175 return 1 if !$readit && $file =~ /\.pod$/i;
190 my $path = join('/',$dir,$file);
191 return $path if -f $path and -r _;
192 if (!$opt_i or $Is_VMS or $Is_MSWin32 or $Is_Dos or $^O eq 'os2') {
193 # on a case-forgiving file system or if case is important
194 # that is it all we can do
195 warn "Ignored $path: unreadable\n" if -f _;
202 foreach $p (split(/\//, $file)){
207 if ( $p eq $global_target) {
208 my $tmp_path = join ('/', @p);
210 for (@global_found) {
211 $path_f = 1 if $_ eq $tmp_path;
213 push (@global_found, $tmp_path) unless $path_f;
214 print STDERR "Found as @p but directory\n" if $opt_v;
217 elsif (-f _ && -r _) {
221 warn "Ignored $try: unreadable\n";
227 while ($cip=readdir(DIR)) {
228 if (lc $cip eq $lcp){
234 return "" unless $found;
236 return "@p" if -f "@p" and -r _;
237 warn "Ignored @p: unreadable\n" if -f _;
246 return "" if length $dir and not -d $dir;
248 return minus_f_nocase($dir,$file);
251 my $path = minus_f_nocase($dir,$file);
252 return $path if length $path and containspod($path);
259 my($recurse,$s,@dirs) = @_;
261 $s = VMS::Filespec::unixify($s) if $Is_VMS;
262 return $s if -f $s && containspod($s);
263 printf STDERR "Looking for $s in @dirs\n" if $opt_v;
267 $global_target = (split('/', $s))[-1];
268 for ($i=0; $i<@dirs; $i++) {
270 ($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
271 if ( ( $ret = check_file $dir,"$s.pod")
272 or ( $ret = check_file $dir,"$s.pm")
273 or ( $ret = check_file $dir,$s)
275 $ret = check_file $dir,"$s.com")
276 or ( $^O eq 'os2' and
277 $ret = check_file $dir,"$s.cmd")
278 or ( ($Is_MSWin32 or $Is_Dos or $^O eq 'os2') and
279 $ret = check_file $dir,"$s.bat")
280 or ( $ret = check_file "$dir/pod","$s.pod")
281 or ( $ret = check_file "$dir/pod",$s)
282 or ( $ret = check_file "$dir/pods","$s.pod")
283 or ( $ret = check_file "$dir/pods",$s)
290 my @newdirs = map "$dir/$_", grep {
292 not /^auto$/ and # save time! don't search auto dirs
296 next unless @newdirs;
297 @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
298 print STDERR "Also looking in @newdirs\n" if $opt_v;
299 push(@dirs,@newdirs);
306 my @data = split /\n{2,}/, shift;
307 shift @data while @data and $data[0] !~ /\S/; # Go to header
308 shift @data if @data and $data[0] =~ /Contributed\s+Perl/; # Skip header
309 pop @data if @data and $data[-1] =~ /^\w/; # Skip footer, like
310 # 28/Jan/99 perl 5.005, patch 53 1
315 my ($file, $tmp, $filter) = @_;
319 open(OUT,">>$tmp") or warn("Can't open $tmp: $!"), return;
320 Pod::Text->new()->parse_from_file($file,\*OUT);
324 my $cmd = "pod2man --lax $file | nroff -man";
325 $cmd .= " | col -x" if $^O =~ /hpux/;
327 $rslt = filter_nroff($rslt) if $filter;
328 unless (($err = $?)) {
329 open(TMP,">>$tmp") or warn("Can't open $tmp: $!"), return;
334 if ($opt_u or $err or -z $tmp) {
335 open(OUT,">>$tmp") or warn("Can't open $tmp: $!"), return;
336 open(IN,"<$file") or warn("Can't open $file: $!"), return;
339 $cut = $1 eq 'cut' if /^=(\w+)/;
349 my ($tmp, $no_tty, @pagers) = @_;
351 open(TMP,"<$tmp") or warn("Can't open $tmp: $!"), return;
356 foreach my $pager (@pagers) {
357 system("$pager $tmp") or last;
365 1 while unlink($_); #Possibly pointless VMSism
370 my ($val, @files) = @_;
376 my ($msg, @files) = @_;
383 if ($podidx && open(PODIDX, $podidx)) {
386 $searchfor =~ s,::,/,g;
387 print STDERR "Searching for '$searchfor' in $podidx\n" if $opt_v;
390 push(@found, $_) if m,/$searchfor(?:\.(?:pod|pm))?$,i;
395 print STDERR "Searching for $_\n" if $opt_v;
396 # We must look both in @INC for library modules and in PATH
397 # for executables, like h2xs or perldoc itself.
398 my @searchdirs = @INC;
401 push @found, $_ if $opt_m or containspod($_);
407 for ($i = 0; $trn = $ENV{'DCL$PATH;'.$i}; $i++) {
408 push(@searchdirs,$trn);
410 push(@searchdirs,'perl_root:[lib.pod]') # installed pods
413 push(@searchdirs, grep(-d, split($Config{path_sep},
417 my @files = searchfor(0,$_,@searchdirs);
419 print STDERR "Found as @files\n" if $opt_v;
422 # no match, try recursive search
423 @searchdirs = grep(!/^\.$/,@INC);
424 @files= searchfor(1,$_,@searchdirs) if $opt_r;
426 print STDERR "Loosely found as @files\n" if $opt_v;
429 print STDERR "No documentation found for \"$_\".\n";
431 print STDERR "However, try\n";
432 for my $dir (@global_found) {
433 opendir(DIR, $dir) or die "$!";
434 while (my $file = readdir(DIR)) {
435 next if ($file =~ /^\./);
436 $file =~ s/\.(pm|pod)$//;
437 print STDERR "\tperldoc $_\::$file\n";
448 exit ($Is_VMS ? 98962 : 1);
452 print join("\n", @found), "\n";
456 my $lines = $ENV{LINES} || 24;
459 if (! -t STDOUT) { $no_tty = 1 }
461 # until here we could simply exit or die
462 # now we create temporary files that we have to clean up
463 # namely $tmp, $buffer
468 $tmp = "$ENV{TEMP}\\perldoc1.$$";
469 $buffer = "$ENV{TEMP}\\perldoc1.b$$";
470 push @pagers, qw( more< less notepad );
471 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
472 for (@found) { s,/,\\,g }
475 $tmp = 'Sys$Scratch:perldoc.tmp1_'.$$;
476 $buffer = 'Sys$Scratch:perldoc.tmp1_b'.$$;
477 push @pagers, qw( most more less type/page );
480 $tmp = "$ENV{TEMP}/perldoc1.$$";
481 $buffer = "$ENV{TEMP}/perldoc1.b$$";
483 $buffer =~ tr!\\/!//!s;
484 push @pagers, qw( less.exe more.com< );
485 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
490 $tmp = POSIX::tmpnam();
491 $buffer = POSIX::tmpnam();
492 unshift @pagers, 'less', 'cmd /c more <';
495 $tmp = "/tmp/perldoc1.$$";
496 $buffer = "/tmp/perldoc1.b$$";
498 push @pagers, qw( more less pg view cat );
499 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
501 unshift @pagers, $ENV{PERLDOC_PAGER} if $ENV{PERLDOC_PAGER};
503 # all exit calls from here on have to be safe_exit calls (see above)
504 # and all die calls safe_die calls to guarantee removal of files and
508 foreach my $pager (@pagers) {
509 system("$pager @found") or safe_exit(0, $tmp, $buffer);
511 if ($Is_VMS) { eval 'use vmsish qw(status exit); exit $?' }
512 # I don't get the line above. Please patch yourself as needed.
513 safe_exit(1, $tmp, $buffer);
518 my $perlfunc = shift @found;
519 open(PFUNC, $perlfunc)
520 or safe_die("Can't open $perlfunc: $!", $tmp, $buffer);
522 # Functions like -r, -e, etc. are listed under `-X'.
523 my $search_string = ($opt_f =~ /^-[rwxoRWXOeszfdlpSbctugkTBMAC]$/)
528 last if /^=head2 Alphabetical Listing of Perl Functions/;
531 # Look for our function
535 if (/^=item\s+\Q$search_string\E\b/o) {
539 last if $found > 1 and not $inlist;
549 ++$found if /^\w/; # found descriptive text
552 die "No documentation for perl function `$opt_f' found\n";
557 local @ARGV = @found; # I'm lazy, sue me.
562 if (/^=head2\s+.*(?:$opt_q)/oi) {
564 push @pod, "=head1 Found in $ARGV\n\n" unless $found_in{$ARGV}++;
573 safe_die("No documentation for perl FAQ keyword `$opt_q' found\n",
581 open(TMP,">$buffer") or safe_die("Can't open '$buffer': $!", $tmp, $buffer);
582 print TMP "=over 8\n\n";
591 printout($_, $tmp, $filter);
593 page($tmp, $no_tty, @pagers);
595 safe_exit(0, $tmp, $buffer);
601 perldoc - Look up Perl documentation in pod format.
605 B<perldoc> [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] [B<-F>] [B<-X>] PageName|ModuleName|ProgramName
607 B<perldoc> B<-f> BuiltinFunction
609 B<perldoc> B<-q> FAQ Keyword
613 I<perldoc> looks up a piece of documentation in .pod format that is embedded
614 in the perl installation tree or in a perl script, and displays it via
615 C<pod2man | nroff -man | $PAGER>. (In addition, if running under HP-UX,
616 C<col -x> will be used.) This is primarily used for the documentation for
617 the perl library modules.
619 Your system may also have man pages installed for those modules, in
620 which case you can probably just use the man(1) command.
628 Prints out a brief help message.
632 Describes search for the item in detail.
634 =item B<-t> text output
636 Display docs using plain text converter, instead of nroff. This may be faster,
637 but it won't look as nice.
639 =item B<-u> unformatted
641 Find docs only; skip reformatting by pod2*
645 Display the entire module: both code and unformatted pod documentation.
646 This may be useful if the docs don't explain a function in the detail
647 you need, and you'd like to inspect the code directly; perldoc will find
648 the file for you and simply hand it off for display.
650 =item B<-l> file name only
652 Display the file name of the module found.
654 =item B<-F> file names
656 Consider arguments as file names, no search in directories will be performed.
660 The B<-f> option followed by the name of a perl built in function will
661 extract the documentation of this function from L<perlfunc>.
665 The B<-q> option takes a regular expression as an argument. It will search
666 the question headings in perlfaq[1-9] and print the entries matching
667 the regular expression.
669 =item B<-X> use an index if present
671 The B<-X> option looks for a entry whose basename matches the name given on the
672 command line in the file C<$Config{archlib}/pod.idx>. The pod.idx file should
673 contain fully qualified filenames, one per line.
675 =item B<PageName|ModuleName|ProgramName>
677 The item you want to look up. Nested modules (such as C<File::Basename>)
678 are specified either as C<File::Basename> or C<File/Basename>. You may also
679 give a descriptive name of a page, such as C<perlfunc>. You may also give a
680 partial or wrong-case name, such as "basename" for "File::Basename", but
681 this will be slower, if there is more then one page with the same partial
682 name, you will only get the first one.
688 Any switches in the C<PERLDOC> environment variable will be used before the
689 command line arguments. C<perldoc> also searches directories
690 specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
691 defined) and C<PATH> environment variables.
692 (The latter is so that embedded pods for executables, such as
693 C<perldoc> itself, are available.) C<perldoc> will use, in order of
694 preference, the pager defined in C<PERLDOC_PAGER>, C<MANPAGER>, or
695 C<PAGER> before trying to find a pager on its own. (C<MANPAGER> is not
696 used if C<perldoc> was told to display plain text or unformatted pod.)
698 One useful value for C<PERLDOC_PAGER> is C<less -+C -E>.
702 This is perldoc v2.0.
706 Kenneth Albanowski <kjahds@kjahds.com>
708 Minor updates by Andy Dougherty <doughera@lafcol.lafayette.edu>,
714 # Version 1.15: Tue Aug 24 01:50:20 EST 1999
715 # Charles Wilson <cwilson@ece.gatech.edu>
716 # changed /pod/ directory to /pods/ for cygwin
717 # to support cygwin/win32
718 # Version 1.14: Wed Jul 15 01:50:20 EST 1998
719 # Robin Barker <rmb1@cise.npl.co.uk>
720 # -strict, -w cleanups
721 # Version 1.13: Fri Feb 27 16:20:50 EST 1997
722 # Gurusamy Sarathy <gsar@umich.edu>
723 # -doc tweaks for -F and -X options
724 # Version 1.12: Sat Apr 12 22:41:09 EST 1997
725 # Gurusamy Sarathy <gsar@umich.edu>
726 # -various fixes for win32
727 # Version 1.11: Tue Dec 26 09:54:33 EST 1995
728 # Kenneth Albanowski <kjahds@kjahds.com>
729 # -added Charles Bailey's further VMS patches, and -u switch
730 # -added -t switch, with pod2text support
732 # Version 1.10: Thu Nov 9 07:23:47 EST 1995
733 # Kenneth Albanowski <kjahds@kjahds.com>
735 # -added better error recognition (on no found pages, just exit. On
736 # missing nroff/pod2man, just display raw pod.)
737 # -added recursive/case-insensitive matching (thanks, Andreas). This
738 # slows things down a bit, unfortunately. Give a precise name, and
741 # Version 1.01: Tue May 30 14:47:34 EDT 1995
742 # Andy Dougherty <doughera@lafcol.lafayette.edu>
743 # -added pod documentation.
744 # -added PATH searching.
745 # -added searching pod/ subdirectory (mainly to pick up perlfunc.pod
751 # Cache directories read during sloppy match
754 close OUT or die "Can't close $file: $!";
755 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
756 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';