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
65 $Is_VMS = $^O eq 'VMS';
66 $Is_MSWin32 = $^O eq 'MSWin32';
70 # Erase evidence of previous errors (if any), so exit status is simple.
73 perldoc [options] PageName|ModuleName|ProgramName...
74 perldoc [options] -f BuiltinFunction
77 -h Display this help message
78 -t Display pod using pod2text instead of pod2man and nroff
79 (-t is the default on win32)
80 -u Display unformatted pod text
81 -m Display modules file in its entirety
82 -l Display the modules file name
83 -v Verbosely describe what's going on
85 PageName|ModuleName...
86 is the name of a piece of documentation that you want to look at. You
87 may either give a descriptive name of the page (as in the case of
88 `perlfunc') the name of a module, either like `Term::Info',
89 `Term/Info', the partial name of a module, like `info', or
90 `makemaker', or the name of a program, like `perldoc'.
93 is the name of a perl function. Will extract documentation from
96 Any switches in the PERLDOC environment variable will be used before the
97 command line arguments.
102 use Text::ParseWords;
105 unshift(@ARGV,shellwords($ENV{"PERLDOC"}));
107 getopts("mhtluvf:") || usage;
109 usage if $opt_h || $opt_h; # avoid -w warning
111 if ($opt_t + $opt_u + $opt_m + $opt_l > 1) {
112 usage("only one of -t, -u, -m or -l")
113 } elsif ($Is_MSWin32) {
114 $opt_t = 1 unless $opt_t + $opt_u + $opt_m + $opt_l;
117 if ($opt_t) { require Pod::Text; import Pod::Text; }
120 @pages = ("perlfunc");
125 # Does this look like a module or extension directory?
126 if (-f "Makefile.PL") {
127 # Add ., lib and blib/* libs to @INC (if they exist)
129 unshift(@INC, 'lib') if -d 'lib';
130 require ExtUtils::testlib;
136 my($file, $readit) = @_;
137 return 1 if !$readit && $file =~ /\.pod$/i;
152 # on a case-forgiving file system we can simply use -f $file
153 if ($Is_VMS or $Is_MSWin32 or $^O eq 'os2') {
154 return $file if -f $file and -r _;
155 warn "Ignored $file: unreadable\n" unless -r _;
161 foreach $p (split(/\//, $file)){
166 if ( $p eq $global_target) {
167 $tmp_path = join ('/', @p);
169 for (@global_found) {
170 $path_f = 1 if $_ eq $tmp_path;
172 push (@global_found, $tmp_path) unless $path_f;
173 print STDERR "Found as @p but directory\n" if $opt_v;
175 } elsif (-f _ && -r _) {
178 warn "Ignored $try: unreadable\n";
183 while ($cip=readdir(DIR)) {
184 if (lc $cip eq $lcp){
190 return "" unless $found;
192 return "@p" if -f "@p" and -r _;
193 warn "Ignored $file: unreadable\n" if -f _;
196 return; # is not a file
202 return minus_f_nocase($file) && containspod($file) ? $file : "";
207 my($recurse,$s,@dirs) = @_;
209 $s = VMS::Filespec::unixify($s) if $Is_VMS;
210 return $s if -f $s && containspod($s);
211 printf STDERR "Looking for $s in @dirs\n" if $opt_v;
215 $global_target = (split('/', $s))[-1];
216 for ($i=0; $i<@dirs; $i++) {
218 ($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
219 if ( ( $ret = check_file "$dir/$s.pod")
220 or ( $ret = check_file "$dir/$s.pm")
221 or ( $ret = check_file "$dir/$s")
223 $ret = check_file "$dir/$s.com")
224 or ( $^O eq 'os2' and
225 $ret = check_file "$dir/$s.cmd")
226 or ( ($Is_MSWin32 or $^O eq 'os2') and
227 $ret = check_file "$dir/$s.bat")
228 or ( $ret = check_file "$dir/pod/$s.pod")
229 or ( $ret = check_file "$dir/pod/$s")
236 my @newdirs = map "$dir/$_", grep {
238 not /^auto$/ and # save time! don't search auto dirs
242 next unless @newdirs;
243 @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
244 print STDERR "Also looking in @newdirs\n" if $opt_v;
245 push(@dirs,@newdirs);
253 print STDERR "Searching for $_\n" if $opt_v;
254 # We must look both in @INC for library modules and in PATH
255 # for executables, like h2xs or perldoc itself.
260 for ($i = 0; $trn = $ENV{'DCL$PATH'.$i}; $i++) {
261 push(@searchdirs,$trn);
264 push(@searchdirs, grep(-d, split($Config{path_sep},
267 @files= searchfor(0,$_,@searchdirs);
270 print STDERR "Found as @files\n" if $opt_v;
272 # no match, try recursive search
274 @searchdirs = grep(!/^\.$/,@INC);
276 @files= searchfor(1,$_,@searchdirs);
278 print STDERR "Loosely found as @files\n" if $opt_v;
280 print STDERR "No documentation found for \"$_\".\n";
282 print STDERR "However, try\n";
283 my $dir = $file = "";
284 for $dir (@global_found) {
285 opendir(DIR, $dir) or die "$!";
286 while ($file = readdir(DIR)) {
287 next if ($file =~ /^\./);
288 $file =~ s/\.(pm|pod)$//;
289 print STDERR "\tperldoc $_\::$file\n";
300 exit ($Is_VMS ? 98962 : 1);
304 print join("\n", @found), "\n";
308 if( ! -t STDOUT ) { $no_tty = 1 }
311 $tmp = "$ENV{TEMP}\\perldoc1.$$";
312 push @pagers, qw( more< less notepad );
313 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
315 $tmp = 'Sys$Scratch:perldoc.tmp1_'.$$;
316 push @pagers, qw( most more less type/page );
320 $tmp = POSIX::tmpnam();
322 $tmp = "/tmp/perldoc1.$$";
324 push @pagers, qw( more less pg view cat );
325 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
327 unshift @pagers, $ENV{PERLDOC_PAGER} if $ENV{PERLDOC_PAGER};
330 foreach $pager (@pagers) {
331 system("$pager @found") or exit;
333 if ($Is_VMS) { eval 'use vmsish qw(status exit); exit $?' }
338 my $perlfunc = shift @found;
339 open(PFUNC, $perlfunc) or die "Can't open $perlfunc: $!";
343 last if /^=head2 Alphabetical Listing of Perl Functions/;
346 # Look for our function
350 if (/^=item\s+\Q$opt_f\E\b/o) {
357 ++$found if /^\w/; # found descriptive text
361 open(FORMATTER, "| pod2text") || die "Can't start filter";
362 print FORMATTER "=over 8\n\n";
363 print FORMATTER @pod;
364 print FORMATTER "=back\n";
370 die "No documentation for perl function `$opt_f' found\n";
379 Pod::Text::pod2text($_,*TMP);
381 } elsif(not $opt_u) {
382 my $cmd = "pod2man --lax $_ | nroff -man";
383 $cmd .= " | col -x" if $^O =~ /hpux/;
385 unless(($err = $?)) {
392 if( $opt_u or $err or -z $tmp) {
397 $cut = $1 eq 'cut' if /^=(\w+)/;
411 foreach $pager (@pagers) {
412 system("$pager $tmp") or last;
416 1 while unlink($tmp); #Possibly pointless VMSism
424 perldoc - Look up Perl documentation in pod format.
428 B<perldoc> [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] PageName|ModuleName|ProgramName
430 B<perldoc> B<-f> BuiltinFunction
434 I<perldoc> looks up a piece of documentation in .pod format that is embedded
435 in the perl installation tree or in a perl script, and displays it via
436 C<pod2man | nroff -man | $PAGER>. (In addition, if running under HP-UX,
437 C<col -x> will be used.) This is primarily used for the documentation for
438 the perl library modules.
440 Your system may also have man pages installed for those modules, in
441 which case you can probably just use the man(1) command.
449 Prints out a brief help message.
453 Describes search for the item in detail.
455 =item B<-t> text output
457 Display docs using plain text converter, instead of nroff. This may be faster,
458 but it won't look as nice.
460 =item B<-u> unformatted
462 Find docs only; skip reformatting by pod2*
466 Display the entire module: both code and unformatted pod documentation.
467 This may be useful if the docs don't explain a function in the detail
468 you need, and you'd like to inspect the code directly; perldoc will find
469 the file for you and simply hand it off for display.
471 =item B<-l> file name only
473 Display the file name of the module found.
477 The B<-f> option followed by the name of a perl built in function will
478 extract the documentation of this function from L<perlfunc>.
480 =item B<PageName|ModuleName|ProgramName>
482 The item you want to look up. Nested modules (such as C<File::Basename>)
483 are specified either as C<File::Basename> or C<File/Basename>. You may also
484 give a descriptive name of a page, such as C<perlfunc>. You make also give a
485 partial or wrong-case name, such as "basename" for "File::Basename", but
486 this will be slower, if there is more then one page with the same partial
487 name, you will only get the first one.
493 Any switches in the C<PERLDOC> environment variable will be used before the
494 command line arguments. C<perldoc> also searches directories
495 specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
496 defined) and C<PATH> environment variables.
497 (The latter is so that embedded pods for executables, such as
498 C<perldoc> itself, are available.)
502 Kenneth Albanowski <kjahds@kjahds.com>
504 Minor updates by Andy Dougherty <doughera@lafcol.lafayette.edu>
509 # Version 1.12: Sat Apr 12 22:41:09 EST 1997
510 # Gurusamy Sarathy <gsar@umich.edu>
511 # -various fixes for win32
512 # Version 1.11: Tue Dec 26 09:54:33 EST 1995
513 # Kenneth Albanowski <kjahds@kjahds.com>
514 # -added Charles Bailey's further VMS patches, and -u switch
515 # -added -t switch, with pod2text support
517 # Version 1.10: Thu Nov 9 07:23:47 EST 1995
518 # Kenneth Albanowski <kjahds@kjahds.com>
520 # -added better error recognition (on no found pages, just exit. On
521 # missing nroff/pod2man, just display raw pod.)
522 # -added recursive/case-insensitive matching (thanks, Andreas). This
523 # slows things down a bit, unfortunately. Give a precise name, and
526 # Version 1.01: Tue May 30 14:47:34 EDT 1995
527 # Andy Dougherty <doughera@lafcol.lafayette.edu>
528 # -added pod documentation.
529 # -added PATH searching.
530 # -added searching pod/ subdirectory (mainly to pick up perlfunc.pod
536 # Cache directories read during sloppy match
539 close OUT or die "Can't close $file: $!";
540 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
541 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';