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)) =~ s/\.PL$//;
18 if ($^O eq 'VMS' or $^O eq 'os2'); # "case-forgiving"
20 open OUT,">$file" or die "Can't create $file: $!";
22 print "Extracting $file (with variable substitutions)\n";
24 # In this section, perl variables will be expanded during extraction.
25 # You can use $Config{...} to use Configure variables.
27 print OUT <<"!GROK!THIS!";
29 eval 'exec perl -S \$0 "\$@"'
33 # In the following, perl variables are not expanded during extraction.
35 print OUT <<'!NO!SUBS!';
36 eval 'exec perl -S $0 "$@"'
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.
49 Usage: $0 [-h] [-v] [-t] [-u] [-m] PageName|ModuleName|ProgramName
51 We suggest you use "perldoc perldoc" to get aquainted
57 $Is_VMS = $^O eq 'VMS';
62 perldoc [-h] [-v] [-u] PageName|ModuleName|ProgramName...
63 -h Display this help message.
64 -t Display pod using pod2text instead of pod2man and nroff.
65 -u Display unformatted pod text
66 -m Display modules file in its entirety
67 -v Verbosely describe what's going on.
68 PageName|ModuleName...
69 is the name of a piece of documentation that you want to look at. You
70 may either give a descriptive name of the page (as in the case of
71 `perlfunc') the name of a module, either like `Term::Info',
72 `Term/Info', the partial name of a module, like `info', or
73 `makemaker', or the name of a program, like `perldoc'.
75 Any switches in the PERLDOC environment variable will be used before the
76 command line arguments.
84 unshift(@ARGV,shellwords($ENV{"PERLDOC"}));
86 getopts("mhtuv") || usage;
88 usage if $opt_h || $opt_h; # avoid -w warning
90 usage("only one of -t, -u, or -m") if $opt_t + $opt_u + $opt_m > 1;
92 if ($opt_t) { require Pod::Text; import Pod::Text; }
115 foreach $p (split(/\//, $file)){
116 if ($Is_VMS and not scalar @p) {
117 # VMS filesystems don't begin at '/'
123 } elsif (-f ("@p/$p")) {
129 while ($cip=readdir(DIR)) {
130 $cip =~ s/\.dir$// if $Is_VMS;
131 if (lc $cip eq $lcp){
137 return "" unless $found;
139 return "@p" if -f "@p";
142 return; # is not a file
146 my($recurse,$s,@dirs) = @_;
148 $s = VMS::Filespec::unixify($s) if $Is_VMS;
149 printf STDERR "looking for $s in @dirs\n" if $opt_v;
153 for ($i=0;$i<@dirs;$i++) {
155 ($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
156 if (( $ret = minus_f_nocase "$dir/$s.pod")
157 or ( $ret = minus_f_nocase "$dir/$s.pm" and containspod($ret))
158 or ( $ret = minus_f_nocase "$dir/$s" and containspod($ret))
160 $ret = minus_f_nocase "$dir/$s.com" and containspod($ret))
161 or ( $ret = minus_f_nocase "$dir/pod/$s.pod")
162 or ( $ret = minus_f_nocase "$dir/pod/$s" and containspod($ret)))
167 my(@newdirs) = grep(-d,map("$dir/$_",grep(!/^\.\.?$/,readdir(D))));
169 @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
170 next unless @newdirs;
171 print STDERR "Also looking in @newdirs\n" if $opt_v;
172 push(@dirs,@newdirs);
180 print STDERR "Searching for $_\n" if $opt_v;
181 # We must look both in @INC for library modules and in PATH
182 # for executables, like h2xs or perldoc itself.
187 for ($i = 0; $trn = $ENV{'DCL$PATH'.$i}; $i++) {
188 push(@searchdirs,$trn);
191 push(@searchdirs, grep(-d, split(':', $ENV{'PATH'})));
193 @files= searchfor(0,$_,@searchdirs);
196 print STDERR "Found as @files\n" if $opt_v;
198 # no match, try recursive search
200 @searchdirs = grep(!/^\.$/,@INC);
203 @files= searchfor(1,$_,@searchdirs);
205 print STDERR "Loosely found as @files\n" if $opt_v;
207 print STDERR "No documentation found for '$_'\n";
214 exit ($Is_VMS ? 98962 : 1);
217 if( ! -t STDOUT ) { $opt_f = 1 }
220 $tmp = "/tmp/perldoc1.$$";
222 @pagers = qw( more less pg view cat );
223 unshift(@pagers,$ENV{PAGER}) if $ENV{PAGER};
225 $tmp = 'Sys$Scratch:perldoc.tmp1_'.$$;
226 @pagers = qw( most more less type/page );
227 unshift(@pagers,$ENV{PERLDOC_PAGER}) if $ENV{PERLDOC_PAGER};
232 foreach $pager (@pagers) {
233 my($sts) = system("$pager @found");
234 exit 0 if ($Is_VMS ? ($sts & 1) : !$sts);
236 exit $Is_VMS ? $sts : 1;
243 Pod::Text::pod2text($_,*TMP);
245 } elsif(not $opt_u) {
248 $rslt = `pod2man $_ | nroff -man | col -x`;
250 $rslt = `pod2man $_ | nroff -man`;
252 if ($Is_VMS) { $err = !($? % 2) || $rslt =~ /IVVERB/; }
254 print TMP $rslt unless $err;
258 if( $opt_u or $err or -z $tmp) {
263 $cut = $1 eq 'cut' if /^=(\w+)/;
277 foreach $pager (@pagers) {
278 $sts = system("$pager $tmp");
279 last if $Is_VMS && ($sts & 1);
284 1 while unlink($tmp); #Possibly pointless VMSism
292 perldoc - Look up Perl documentation in pod format.
296 B<perldoc> [B<-h>] [B<-v>] [B<-t>] [B<-u>] PageName|ModuleName|ProgramName
300 I<perldoc> looks up a piece of documentation in .pod format that is embedded
301 in the perl installation tree or in a perl script, and displays it via
302 C<pod2man | nroff -man | $PAGER>. (In addition, if running under HP-UX,
303 C<col -x> will be used.) This is primarily used for the documentation for
304 the perl library modules.
306 Your system may also have man pages installed for those modules, in
307 which case you can probably just use the man(1) command.
315 Prints out a brief help message.
319 Describes search for the item in detail.
321 =item B<-t> text output
323 Display docs using plain text converter, instead of nroff. This may be faster,
324 but it won't look as nice.
326 =item B<-u> unformatted
328 Find docs only; skip reformatting by pod2*
332 Display the entire module: both code and unformatted pod documentation.
333 This may be useful if the docs don't explain a function in the detail
334 you need, and you'd like to inspect the code directly; perldoc will find
335 the file for you and simply hand it off for display.
337 =item B<PageName|ModuleName|ProgramName>
339 The item you want to look up. Nested modules (such as C<File::Basename>)
340 are specified either as C<File::Basename> or C<File/Basename>. You may also
341 give a descriptive name of a page, such as C<perlfunc>. You make also give a
342 partial or wrong-case name, such as "basename" for "File::Basename", but
343 this will be slower, if there is more then one page with the same partial
344 name, you will only get the first one.
350 Any switches in the C<PERLDOC> environment variable will be used before the
351 command line arguments. C<perldoc> also searches directories
352 specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
353 defined) and C<PATH> environment variables.
354 (The latter is so that embedded pods for executables, such as
355 C<perldoc> itself, are available.)
359 Kenneth Albanowski <kjahds@kjahds.com>
361 Minor updates by Andy Dougherty <doughera@lafcol.lafayette.edu>
370 # Version 1.11: Tue Dec 26 09:54:33 EST 1995
371 # Kenneth Albanowski <kjahds@kjahds.com>
372 # -added Charles Bailey's further VMS patches, and -u switch
373 # -added -t switch, with pod2text support
375 # Version 1.10: Thu Nov 9 07:23:47 EST 1995
376 # Kenneth Albanowski <kjahds@kjahds.com>
378 # -added better error recognition (on no found pages, just exit. On
379 # missing nroff/pod2man, just display raw pod.)
380 # -added recursive/case-insensitive matching (thanks, Andreas). This
381 # slows things down a bit, unfortunately. Give a precise name, and
384 # Version 1.01: Tue May 30 14:47:34 EDT 1995
385 # Andy Dougherty <doughera@lafcol.lafayette.edu>
386 # -added pod documentation.
387 # -added PATH searching.
388 # -added searching pod/ subdirectory (mainly to pick up perlfunc.pod
394 # Cache directories read during sloppy match
397 close OUT or die "Can't close $file: $!";
398 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
399 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';