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+"\$@"}'
31 if \$running_under_some_shell;
34 push \@pagers, "$Config{'pager'}" if -x "$Config{'pager'}";
37 # In the following, perl variables are not expanded during extraction.
39 print OUT <<'!NO!SUBS!';
42 # Perldoc revision #1 -- look up a piece of documentation in .pod format that
43 # is embedded in the perl installation tree.
45 # This is not to be confused with Tom Christianson's perlman, which is a
46 # man replacement, written in perl. This perldoc is strictly for reading
47 # the perl manuals, though it too is written in perl.
50 $me = $0; # Editing $0 is unportable
53 Usage: $me [-h] [-r] [-i] [-v] [-t] [-u] [-m] [-l] [-F] [-X] PageName|ModuleName|ProgramName
57 The -h option prints more help. Also try "perldoc perldoc" to get
58 aquainted with the system.
68 $Is_VMS = $^O eq 'VMS';
69 $Is_MSWin32 = $^O eq 'MSWin32';
70 $Is_Dos = $^O eq 'dos';
74 # Erase evidence of previous errors (if any), so exit status is simple.
77 perldoc [options] PageName|ModuleName|ProgramName...
78 perldoc [options] -f BuiltinFunction
79 perldoc [options] -q FAQRegex
82 -h Display this help message
83 -r Recursive search (slow)
85 -t Display pod using pod2text instead of pod2man and nroff
86 (-t is the default on win32)
87 -u Display unformatted pod text
88 -m Display module's file in its entirety
89 -l Display the module's file name
90 -F Arguments are file names, not modules
91 -v Verbosely describe what's going on
92 -X use index if present (looks for pod.idx at $Config{archlib})
95 PageName|ModuleName...
96 is the name of a piece of documentation that you want to look at. You
97 may either give a descriptive name of the page (as in the case of
98 `perlfunc') the name of a module, either like `Term::Info',
99 `Term/Info', the partial name of a module, like `info', or
100 `makemaker', or the name of a program, like `perldoc'.
103 is the name of a perl function. Will extract documentation from
107 is a regex. Will search perlfaq[1-9] for and extract any
108 questions that match.
110 Any switches in the PERLDOC environment variable will be used before the
111 command line arguments. The optional pod index file contains a list of
112 filenames, one per line.
117 use Text::ParseWords;
120 unshift(@ARGV,shellwords($ENV{"PERLDOC"}));
122 getopts("mhtluvriFf:Xq:") || usage;
124 usage if $opt_h || $opt_h; # avoid -w warning
127 $podidx = "$Config{'archlib'}/pod.idx";
128 $podidx = "" unless -f $podidx && -r _ && -M _ <= 7;
131 if ($opt_t + $opt_u + $opt_m + $opt_l > 1) {
132 usage("only one of -t, -u, -m or -l")
133 } elsif ($Is_MSWin32 || $Is_Dos) {
134 $opt_t = 1 unless $opt_t + $opt_u + $opt_m + $opt_l;
137 if ($opt_t) { require Pod::Text; import Pod::Text; }
140 @pages = ("perlfunc");
142 @pages = ("perlfaq1" .. "perlfaq9");
147 # Does this look like a module or extension directory?
148 if (-f "Makefile.PL") {
149 # Add ., lib and blib/* libs to @INC (if they exist)
151 unshift(@INC, 'lib') if -d 'lib';
152 require ExtUtils::testlib;
158 my($file, $readit) = @_;
159 return 1 if !$readit && $file =~ /\.pod$/i;
174 my $path = join('/',$dir,$file);
175 return $path if -f $path and -r _;
176 if (!$opt_i or $Is_VMS or $Is_MSWin32 or $Is_Dos or $^O eq 'os2') {
177 # on a case-forgiving file system or if case is important
178 # that is it all we can do
179 warn "Ignored $file: unreadable\n" if -f _;
186 foreach $p (split(/\//, $file)){
191 if ( $p eq $global_target) {
192 $tmp_path = join ('/', @p);
194 for (@global_found) {
195 $path_f = 1 if $_ eq $tmp_path;
197 push (@global_found, $tmp_path) unless $path_f;
198 print STDERR "Found as @p but directory\n" if $opt_v;
200 } elsif (-f _ && -r _) {
203 warn "Ignored $try: unreadable\n";
208 while ($cip=readdir(DIR)) {
209 if (lc $cip eq $lcp){
215 return "" unless $found;
217 return "@p" if -f "@p" and -r _;
218 warn "Ignored $file: unreadable\n" if -f _;
228 return minus_f_nocase($dir,$file);
230 my $path = minus_f_nocase($dir,$file);
231 return $path if length $path and containspod($path);
238 my($recurse,$s,@dirs) = @_;
240 $s = VMS::Filespec::unixify($s) if $Is_VMS;
241 return $s if -f $s && containspod($s);
242 printf STDERR "Looking for $s in @dirs\n" if $opt_v;
246 $global_target = (split('/', $s))[-1];
247 for ($i=0; $i<@dirs; $i++) {
249 ($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
250 if ( ( $ret = check_file $dir,"$s.pod")
251 or ( $ret = check_file $dir,"$s.pm")
252 or ( $ret = check_file $dir,$s)
254 $ret = check_file $dir,"$s.com")
255 or ( $^O eq 'os2' and
256 $ret = check_file $dir,"$s.cmd")
257 or ( ($Is_MSWin32 or $Is_Dos or $^O eq 'os2') and
258 $ret = check_file $dir,"$s.bat")
259 or ( $ret = check_file "$dir/pod","$s.pod")
260 or ( $ret = check_file "$dir/pod",$s)
267 my @newdirs = map "$dir/$_", grep {
269 not /^auto$/ and # save time! don't search auto dirs
273 next unless @newdirs;
274 @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
275 print STDERR "Also looking in @newdirs\n" if $opt_v;
276 push(@dirs,@newdirs);
284 if ($podidx && open(PODIDX, $podidx)) {
287 $searchfor =~ s,::,/,g;
288 print STDERR "Searching for '$searchfor' in $podidx\n" if $opt_v;
291 push(@found, $_) if m,/$searchfor(?:\.(?:pod|pm))?$,i;
296 print STDERR "Searching for $_\n" if $opt_v;
297 # We must look both in @INC for library modules and in PATH
298 # for executables, like h2xs or perldoc itself.
302 push @found, $_ if $opt_m or containspod($_);
308 for ($i = 0; $trn = $ENV{'DCL$PATH'.$i}; $i++) {
309 push(@searchdirs,$trn);
311 push(@searchdirs,'perl_root:[lib.pod]') # installed pods
313 push(@searchdirs, grep(-d, split($Config{path_sep},
317 @files = searchfor(0,$_,@searchdirs);
319 print STDERR "Found as @files\n" if $opt_v;
321 # no match, try recursive search
323 @searchdirs = grep(!/^\.$/,@INC);
325 @files= searchfor(1,$_,@searchdirs) if $opt_r;
327 print STDERR "Loosely found as @files\n" if $opt_v;
329 print STDERR "No documentation found for \"$_\".\n";
331 print STDERR "However, try\n";
332 my $dir = $file = "";
333 for $dir (@global_found) {
334 opendir(DIR, $dir) or die "$!";
335 while ($file = readdir(DIR)) {
336 next if ($file =~ /^\./);
337 $file =~ s/\.(pm|pod)$//;
338 print STDERR "\tperldoc $_\::$file\n";
349 exit ($Is_VMS ? 98962 : 1);
353 print join("\n", @found), "\n";
357 my $lines = $ENV{LINES} || 24;
359 if( ! -t STDOUT ) { $no_tty = 1 }
362 $tmp = "$ENV{TEMP}\\perldoc1.$$";
363 push @pagers, qw( more< less notepad );
364 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
366 $tmp = 'Sys$Scratch:perldoc.tmp1_'.$$;
367 push @pagers, qw( most more less type/page );
369 $tmp = "$ENV{TEMP}/perldoc1.$$";
371 push @pagers, qw( less.exe more.com< );
372 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
376 $tmp = POSIX::tmpnam();
377 unshift @pagers, 'less', 'cmd /c more <';
379 $tmp = "/tmp/perldoc1.$$";
381 push @pagers, qw( more less pg view cat );
382 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
384 unshift @pagers, $ENV{PERLDOC_PAGER} if $ENV{PERLDOC_PAGER};
387 foreach $pager (@pagers) {
388 system("$pager @found") or exit;
390 if ($Is_VMS) { eval 'use vmsish qw(status exit); exit $?' }
395 my $perlfunc = shift @found;
396 open(PFUNC, $perlfunc) or die "Can't open $perlfunc: $!";
400 last if /^=head2 Alphabetical Listing of Perl Functions/;
403 # Look for our function
407 if (/^=item\s+\Q$opt_f\E\b/o) {
414 ++$found if /^\w/; # found descriptive text
418 open(FORMATTER, "| pod2text") || die "Can't start filter";
419 print FORMATTER "=over 8\n\n";
420 print FORMATTER @pod;
421 print FORMATTER "=back\n";
423 } elsif (@pod < $lines-2) {
426 foreach $pager (@pagers) {
427 open (PAGER, "| $pager") or next;
429 close(PAGER) or next;
434 die "No documentation for perl function `$opt_f' found\n";
440 local @ARGV = @found; # I'm lazy, sue me.
446 if (/^=head2\s+.*$opt_q/oi) {
448 push @pod, "=head1 Found in $ARGV\n\n" unless $found_in{$ARGV}++;
449 } elsif (/^=head2/) {
458 open(FORMATTER, "| pod2text") || die "Can't start filter";
459 print FORMATTER "=over 8\n\n";
460 print FORMATTER @pod;
461 print FORMATTER "=back\n";
463 } elsif (@pod < $lines-2) {
466 foreach $pager (@pagers) {
467 open (PAGER, "| $pager") or next;
469 close(PAGER) or next;
474 die "No documentation for perl FAQ keyword `$opt_q' found\n";
483 Pod::Text::pod2text($_,*TMP);
485 } elsif(not $opt_u) {
486 my $cmd = "pod2man --lax $_ | nroff -man";
487 $cmd .= " | col -x" if $^O =~ /hpux/;
489 unless(($err = $?)) {
496 if( $opt_u or $err or -z $tmp) {
501 $cut = $1 eq 'cut' if /^=(\w+)/;
515 foreach $pager (@pagers) {
516 system("$pager $tmp") or last;
520 1 while unlink($tmp); #Possibly pointless VMSism
528 perldoc - Look up Perl documentation in pod format.
532 B<perldoc> [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] [B<-F>] [B<-X>] PageName|ModuleName|ProgramName
534 B<perldoc> B<-f> BuiltinFunction
536 B<perldoc> B<-q> FAQ Keyword
540 I<perldoc> looks up a piece of documentation in .pod format that is embedded
541 in the perl installation tree or in a perl script, and displays it via
542 C<pod2man | nroff -man | $PAGER>. (In addition, if running under HP-UX,
543 C<col -x> will be used.) This is primarily used for the documentation for
544 the perl library modules.
546 Your system may also have man pages installed for those modules, in
547 which case you can probably just use the man(1) command.
555 Prints out a brief help message.
559 Describes search for the item in detail.
561 =item B<-t> text output
563 Display docs using plain text converter, instead of nroff. This may be faster,
564 but it won't look as nice.
566 =item B<-u> unformatted
568 Find docs only; skip reformatting by pod2*
572 Display the entire module: both code and unformatted pod documentation.
573 This may be useful if the docs don't explain a function in the detail
574 you need, and you'd like to inspect the code directly; perldoc will find
575 the file for you and simply hand it off for display.
577 =item B<-l> file name only
579 Display the file name of the module found.
581 =item B<-F> file names
583 Consider arguments as file names, no search in directories will be performed.
587 The B<-f> option followed by the name of a perl built in function will
588 extract the documentation of this function from L<perlfunc>.
592 The B<-q> option takes a regular expression as an argument. It will search
593 the question headings in perlfaq[1-9] and print the entries matching
594 the regular expression.
596 =item B<-X> use an index if present
598 The B<-X> option looks for a entry whose basename matches the name given on the
599 command line in the file C<$Config{archlib}/pod.idx>. The pod.idx file should
600 contain fully qualified filenames, one per line.
602 =item B<PageName|ModuleName|ProgramName>
604 The item you want to look up. Nested modules (such as C<File::Basename>)
605 are specified either as C<File::Basename> or C<File/Basename>. You may also
606 give a descriptive name of a page, such as C<perlfunc>. You make also give a
607 partial or wrong-case name, such as "basename" for "File::Basename", but
608 this will be slower, if there is more then one page with the same partial
609 name, you will only get the first one.
615 Any switches in the C<PERLDOC> environment variable will be used before the
616 command line arguments. C<perldoc> also searches directories
617 specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
618 defined) and C<PATH> environment variables.
619 (The latter is so that embedded pods for executables, such as
620 C<perldoc> itself, are available.) C<perldoc> will use, in order of
621 preference, the pager defined in C<PERLDOC_PAGER>, C<MANPAGER>, or
622 C<PAGER> before trying to find a pager on its own. (C<MANPAGER> is not
623 used if C<perldoc> was told to display plain text or unformatted pod.)
627 Kenneth Albanowski <kjahds@kjahds.com>
629 Minor updates by Andy Dougherty <doughera@lafcol.lafayette.edu>
634 # Version 1.13: Fri Feb 27 16:20:50 EST 1997
635 # Gurusamy Sarathy <gsar@umich.edu>
636 # -doc tweaks for -F and -X options
637 # Version 1.12: Sat Apr 12 22:41:09 EST 1997
638 # Gurusamy Sarathy <gsar@umich.edu>
639 # -various fixes for win32
640 # Version 1.11: Tue Dec 26 09:54:33 EST 1995
641 # Kenneth Albanowski <kjahds@kjahds.com>
642 # -added Charles Bailey's further VMS patches, and -u switch
643 # -added -t switch, with pod2text support
645 # Version 1.10: Thu Nov 9 07:23:47 EST 1995
646 # Kenneth Albanowski <kjahds@kjahds.com>
648 # -added better error recognition (on no found pages, just exit. On
649 # missing nroff/pod2man, just display raw pod.)
650 # -added recursive/case-insensitive matching (thanks, Andreas). This
651 # slows things down a bit, unfortunately. Give a precise name, and
654 # Version 1.01: Tue May 30 14:47:34 EDT 1995
655 # Andy Dougherty <doughera@lafcol.lafayette.edu>
656 # -added pod documentation.
657 # -added PATH searching.
658 # -added searching pod/ subdirectory (mainly to pick up perlfunc.pod
664 # Cache directories read during sloppy match
667 close OUT or die "Can't close $file: $!";
668 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
669 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';