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] [-n program] [-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 -n Specify replacement for nroff
91 -l Display the module's file name
92 -F Arguments are file names, not modules
93 -v Verbosely describe what's going on
94 -X use index if present (looks for pod.idx at $Config{archlib})
95 -q Search the text of questions (not answers) in perlfaq[1-9]
97 PageName|ModuleName...
98 is the name of a piece of documentation that you want to look at. You
99 may either give a descriptive name of the page (as in the case of
100 `perlfunc') the name of a module, either like `Term::Info',
101 `Term/Info', the partial name of a module, like `info', or
102 `makemaker', or the name of a program, like `perldoc'.
105 is the name of a perl function. Will extract documentation from
109 is a regex. Will search perlfaq[1-9] for and extract any
110 questions that match.
112 Any switches in the PERLDOC environment variable will be used before the
113 command line arguments. The optional pod index file contains a list of
114 filenames, one per line.
119 if (defined $ENV{"PERLDOC"}) {
120 require Text::ParseWords;
121 unshift(@ARGV, Text::ParseWords::shellwords($ENV{"PERLDOC"}));
125 my $getopts = "mhtluvriFf:Xq:n:";
126 print OUT <<"!GET!OPTS!";
128 use vars qw( @{[map "\$opt_$_", ($getopts =~ /\w/g)]} );
130 getopts("$getopts") || usage;
133 print OUT <<'!NO!SUBS!';
136 $opt_n = "nroff" if !$opt_n;
140 $podidx = "$Config{'archlib'}/pod.idx";
141 $podidx = "" unless -f $podidx && -r _ && -M _ <= 7;
144 if ((my $opts = do{ local $^W; $opt_t + $opt_u + $opt_m + $opt_l }) > 1) {
145 usage("only one of -t, -u, -m or -l")
149 || !(exists $ENV{TERM} && $ENV{TERM} !~ /dumb|emacs|none|unknown/i))
151 $opt_t = 1 unless $opts
154 if ($opt_t) { require Pod::Text; import Pod::Text; }
158 @pages = ("perlfunc");
161 @pages = ("perlfaq1" .. "perlfaq9");
167 # Does this look like a module or extension directory?
168 if (-f "Makefile.PL") {
169 # Add ., lib and blib/* libs to @INC (if they exist)
171 unshift(@INC, 'lib') if -d 'lib';
172 require ExtUtils::testlib;
176 my($file, $readit) = @_;
177 return 1 if !$readit && $file =~ /\.pod$/i;
192 my $path = join('/',$dir,$file);
193 return $path if -f $path and -r _;
194 if (!$opt_i or $Is_VMS or $Is_MSWin32 or $Is_Dos or $^O eq 'os2') {
195 # on a case-forgiving file system or if case is important
196 # that is it all we can do
197 warn "Ignored $path: unreadable\n" if -f _;
204 foreach $p (split(/\//, $file)){
209 if ( $p eq $global_target) {
210 my $tmp_path = join ('/', @p);
212 for (@global_found) {
213 $path_f = 1 if $_ eq $tmp_path;
215 push (@global_found, $tmp_path) unless $path_f;
216 print STDERR "Found as @p but directory\n" if $opt_v;
219 elsif (-f _ && -r _) {
223 warn "Ignored $try: unreadable\n";
229 while ($cip=readdir(DIR)) {
230 if (lc $cip eq $lcp){
236 return "" unless $found;
238 return "@p" if -f "@p" and -r _;
239 warn "Ignored @p: unreadable\n" if -f _;
248 return "" if length $dir and not -d $dir;
250 return minus_f_nocase($dir,$file);
253 my $path = minus_f_nocase($dir,$file);
254 return $path if length $path and containspod($path);
261 my($recurse,$s,@dirs) = @_;
263 $s = VMS::Filespec::unixify($s) if $Is_VMS;
264 return $s if -f $s && containspod($s);
265 printf STDERR "Looking for $s in @dirs\n" if $opt_v;
269 $global_target = (split('/', $s))[-1];
270 for ($i=0; $i<@dirs; $i++) {
272 ($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
273 if ( ( $ret = check_file $dir,"$s.pod")
274 or ( $ret = check_file $dir,"$s.pm")
275 or ( $ret = check_file $dir,$s)
277 $ret = check_file $dir,"$s.com")
278 or ( $^O eq 'os2' and
279 $ret = check_file $dir,"$s.cmd")
280 or ( ($Is_MSWin32 or $Is_Dos or $^O eq 'os2') and
281 $ret = check_file $dir,"$s.bat")
282 or ( $ret = check_file "$dir/pod","$s.pod")
283 or ( $ret = check_file "$dir/pod",$s)
284 or ( $ret = check_file "$dir/pods","$s.pod")
285 or ( $ret = check_file "$dir/pods",$s)
292 my @newdirs = map "$dir/$_", grep {
294 not /^auto$/ and # save time! don't search auto dirs
298 next unless @newdirs;
299 @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
300 print STDERR "Also looking in @newdirs\n" if $opt_v;
301 push(@dirs,@newdirs);
308 my @data = split /\n{2,}/, shift;
309 shift @data while @data and $data[0] !~ /\S/; # Go to header
310 shift @data if @data and $data[0] =~ /Contributed\s+Perl/; # Skip header
311 pop @data if @data and $data[-1] =~ /^\w/; # Skip footer, like
312 # 28/Jan/99 perl 5.005, patch 53 1
317 my ($file, $tmp, $filter) = @_;
321 open(OUT,">>$tmp") or warn("Can't open $tmp: $!"), return;
322 Pod::Text->new()->parse_from_file($file,\*OUT);
326 my $cmd = "pod2man --lax $_ | $opt_n -man";
327 $cmd .= " | col -x" if $^O =~ /hpux/;
329 $rslt = filter_nroff($rslt) if $filter;
330 unless (($err = $?)) {
331 open(TMP,">>$tmp") or warn("Can't open $tmp: $!"), return;
336 if ($opt_u or $err or -z $tmp) {
337 open(OUT,">>$tmp") or warn("Can't open $tmp: $!"), return;
338 open(IN,"<$file") or warn("Can't open $file: $!"), return;
341 $cut = $1 eq 'cut' if /^=(\w+)/;
351 my ($tmp, $no_tty, @pagers) = @_;
353 open(TMP,"<$tmp") or warn("Can't open $tmp: $!"), return;
358 foreach my $pager (@pagers) {
359 system("$pager $tmp") or last;
367 1 while unlink($_); #Possibly pointless VMSism
372 my ($val, @files) = @_;
378 my ($msg, @files) = @_;
385 if ($podidx && open(PODIDX, $podidx)) {
388 $searchfor =~ s,::,/,g;
389 print STDERR "Searching for '$searchfor' in $podidx\n" if $opt_v;
392 push(@found, $_) if m,/$searchfor(?:\.(?:pod|pm))?$,i;
397 print STDERR "Searching for $_\n" if $opt_v;
398 # We must look both in @INC for library modules and in PATH
399 # for executables, like h2xs or perldoc itself.
400 my @searchdirs = @INC;
403 push @found, $_ if $opt_m or containspod($_);
409 for ($i = 0; $trn = $ENV{'DCL$PATH;'.$i}; $i++) {
410 push(@searchdirs,$trn);
412 push(@searchdirs,'perl_root:[lib.pod]') # installed pods
415 push(@searchdirs, grep(-d, split($Config{path_sep},
419 my @files = searchfor(0,$_,@searchdirs);
421 print STDERR "Found as @files\n" if $opt_v;
424 # no match, try recursive search
425 @searchdirs = grep(!/^\.$/,@INC);
426 @files= searchfor(1,$_,@searchdirs) if $opt_r;
428 print STDERR "Loosely found as @files\n" if $opt_v;
431 print STDERR "No documentation found for \"$_\".\n";
433 print STDERR "However, try\n";
434 for my $dir (@global_found) {
435 opendir(DIR, $dir) or die "$!";
436 while (my $file = readdir(DIR)) {
437 next if ($file =~ /^\./);
438 $file =~ s/\.(pm|pod)$//;
439 print STDERR "\tperldoc $_\::$file\n";
450 exit ($Is_VMS ? 98962 : 1);
454 print join("\n", @found), "\n";
458 my $lines = $ENV{LINES} || 24;
461 if (! -t STDOUT) { $no_tty = 1 }
463 # until here we could simply exit or die
464 # now we create temporary files that we have to clean up
465 # namely $tmp, $buffer
470 $tmp = "$ENV{TEMP}\\perldoc1.$$";
471 $buffer = "$ENV{TEMP}\\perldoc1.b$$";
472 push @pagers, qw( more< less notepad );
473 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
474 for (@found) { s,/,\\,g }
477 $tmp = 'Sys$Scratch:perldoc.tmp1_'.$$;
478 $buffer = 'Sys$Scratch:perldoc.tmp1_b'.$$;
479 push @pagers, qw( most more less type/page );
482 $tmp = "$ENV{TEMP}/perldoc1.$$";
483 $buffer = "$ENV{TEMP}/perldoc1.b$$";
485 $buffer =~ tr!\\/!//!s;
486 push @pagers, qw( less.exe more.com< );
487 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
492 $tmp = POSIX::tmpnam();
493 $buffer = POSIX::tmpnam();
494 unshift @pagers, 'less', 'cmd /c more <';
497 $tmp = "/tmp/perldoc1.$$";
498 $buffer = "/tmp/perldoc1.b$$";
500 push @pagers, qw( more less pg view cat );
501 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
503 unshift @pagers, $ENV{PERLDOC_PAGER} if $ENV{PERLDOC_PAGER};
505 # all exit calls from here on have to be safe_exit calls (see above)
506 # and all die calls safe_die calls to guarantee removal of files and
510 foreach my $pager (@pagers) {
511 system("$pager @found") or safe_exit(0, $tmp, $buffer);
513 if ($Is_VMS) { eval 'use vmsish qw(status exit); exit $?' }
514 # I don't get the line above. Please patch yourself as needed.
515 safe_exit(1, $tmp, $buffer);
520 my $perlfunc = shift @found;
521 open(PFUNC, $perlfunc)
522 or safe_die("Can't open $perlfunc: $!", $tmp, $buffer);
524 # Functions like -r, -e, etc. are listed under `-X'.
525 my $search_string = ($opt_f =~ /^-[rwxoRWXOeszfdlpSbctugkTBMAC]$/)
530 last if /^=head2 Alphabetical Listing of Perl Functions/;
533 # Look for our function
537 if (/^=item\s+\Q$search_string\E\b/o) {
541 last if $found > 1 and not $inlist;
551 ++$found if /^\w/; # found descriptive text
554 die "No documentation for perl function `$opt_f' found\n";
559 local @ARGV = @found; # I'm lazy, sue me.
562 my $rx = eval { qr/$opt_q/ };
563 die <<EOD unless $rx;
564 Invalid regular expression '$opt_q' given as -q pattern:
566 Did you mean \\Q$opt_q ?
571 if (/^=head2\s+.*(?:$opt_q)/oi) {
573 push @pod, "=head1 Found in $ARGV\n\n" unless $found_in{$ARGV}++;
582 safe_die("No documentation for perl FAQ keyword `$opt_q' found\n",
590 open(TMP,">$buffer") or safe_die("Can't open '$buffer': $!", $tmp, $buffer);
591 print TMP "=over 8\n\n";
600 printout($_, $tmp, $filter);
602 page($tmp, $no_tty, @pagers);
604 safe_exit(0, $tmp, $buffer);
610 perldoc - Look up Perl documentation in pod format.
614 B<perldoc> [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] [B<-F>] [B<-X>] PageName|ModuleName|ProgramName
616 B<perldoc> B<-f> BuiltinFunction
618 B<perldoc> B<-q> FAQ Keyword
622 I<perldoc> looks up a piece of documentation in .pod format that is embedded
623 in the perl installation tree or in a perl script, and displays it via
624 C<pod2man | nroff -man | $PAGER>. (In addition, if running under HP-UX,
625 C<col -x> will be used.) This is primarily used for the documentation for
626 the perl library modules.
628 Your system may also have man pages installed for those modules, in
629 which case you can probably just use the man(1) command.
637 Prints out a brief help message.
641 Describes search for the item in detail.
643 =item B<-t> text output
645 Display docs using plain text converter, instead of nroff. This may be faster,
646 but it won't look as nice.
648 =item B<-u> unformatted
650 Find docs only; skip reformatting by pod2*
654 Display the entire module: both code and unformatted pod documentation.
655 This may be useful if the docs don't explain a function in the detail
656 you need, and you'd like to inspect the code directly; perldoc will find
657 the file for you and simply hand it off for display.
659 =item B<-l> file name only
661 Display the file name of the module found.
663 =item B<-F> file names
665 Consider arguments as file names, no search in directories will be performed.
669 The B<-f> option followed by the name of a perl built in function will
670 extract the documentation of this function from L<perlfunc>.
674 The B<-q> option takes a regular expression as an argument. It will search
675 the question headings in perlfaq[1-9] and print the entries matching
676 the regular expression.
678 =item B<-X> use an index if present
680 The B<-X> option looks for a entry whose basename matches the name given on the
681 command line in the file C<$Config{archlib}/pod.idx>. The pod.idx file should
682 contain fully qualified filenames, one per line.
684 =item B<PageName|ModuleName|ProgramName>
686 The item you want to look up. Nested modules (such as C<File::Basename>)
687 are specified either as C<File::Basename> or C<File/Basename>. You may also
688 give a descriptive name of a page, such as C<perlfunc>. You may also give a
689 partial or wrong-case name, such as "basename" for "File::Basename", but
690 this will be slower, if there is more then one page with the same partial
691 name, you will only get the first one.
697 Any switches in the C<PERLDOC> environment variable will be used before the
698 command line arguments. C<perldoc> also searches directories
699 specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
700 defined) and C<PATH> environment variables.
701 (The latter is so that embedded pods for executables, such as
702 C<perldoc> itself, are available.) C<perldoc> will use, in order of
703 preference, the pager defined in C<PERLDOC_PAGER>, C<MANPAGER>, or
704 C<PAGER> before trying to find a pager on its own. (C<MANPAGER> is not
705 used if C<perldoc> was told to display plain text or unformatted pod.)
707 One useful value for C<PERLDOC_PAGER> is C<less -+C -E>.
711 This is perldoc v2.0.
715 Kenneth Albanowski <kjahds@kjahds.com>
717 Minor updates by Andy Dougherty <doughera@lafcol.lafayette.edu>,
723 # Version 1.15: Tue Aug 24 01:50:20 EST 1999
724 # Charles Wilson <cwilson@ece.gatech.edu>
725 # changed /pod/ directory to /pods/ for cygwin
726 # to support cygwin/win32
727 # Version 1.14: Wed Jul 15 01:50:20 EST 1998
728 # Robin Barker <rmb1@cise.npl.co.uk>
729 # -strict, -w cleanups
730 # Version 1.13: Fri Feb 27 16:20:50 EST 1997
731 # Gurusamy Sarathy <gsar@activestate.com>
732 # -doc tweaks for -F and -X options
733 # Version 1.12: Sat Apr 12 22:41:09 EST 1997
734 # Gurusamy Sarathy <gsar@activestate.com>
735 # -various fixes for win32
736 # Version 1.11: Tue Dec 26 09:54:33 EST 1995
737 # Kenneth Albanowski <kjahds@kjahds.com>
738 # -added Charles Bailey's further VMS patches, and -u switch
739 # -added -t switch, with pod2text support
741 # Version 1.10: Thu Nov 9 07:23:47 EST 1995
742 # Kenneth Albanowski <kjahds@kjahds.com>
744 # -added better error recognition (on no found pages, just exit. On
745 # missing nroff/pod2man, just display raw pod.)
746 # -added recursive/case-insensitive matching (thanks, Andreas). This
747 # slows things down a bit, unfortunately. Give a precise name, and
750 # Version 1.01: Tue May 30 14:47:34 EDT 1995
751 # Andy Dougherty <doughera@lafcol.lafayette.edu>
752 # -added pod documentation.
753 # -added PATH searching.
754 # -added searching pod/ subdirectory (mainly to pick up perlfunc.pod
760 # Cache directories read during sloppy match
763 close OUT or die "Can't close $file: $!";
764 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
765 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';