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 $Config{perlpath} -S \$0 \${1+"\$@"}'
30 if \$running_under_some_shell;
33 push \@pagers, "$Config{'pager'}" if -x "$Config{'pager'}";
36 # In the following, perl variables are not expanded during extraction.
38 print OUT <<'!NO!SUBS!';
41 # Perldoc revision #1 -- look up a piece of documentation in .pod format that
42 # is embedded in the perl installation tree.
44 # This is not to be confused with Tom Christianson's perlman, which is a
45 # man replacement, written in perl. This perldoc is strictly for reading
46 # the perl manuals, though it too is written in perl.
50 Usage: $0 [-h] [-v] [-t] [-u] [-m] [-l] PageName|ModuleName|ProgramName
52 We suggest you use "perldoc perldoc" to get aquainted
58 $Is_VMS = $^O eq 'VMS';
62 # Make sure exit status is success under VMS, so shell doesn't
63 # display error messages left over from startup.
64 ($! = 0, $^E = 1) if $^O eq 'VMS';
66 perldoc [-h] [-v] [-u] PageName|ModuleName|ProgramName...
67 -h Display this help message.
68 -t Display pod using pod2text instead of pod2man and nroff.
69 -u Display unformatted pod text
70 -m Display modules file in its entirety
71 -l Display the modules file name
72 -v Verbosely describe what's going on.
73 PageName|ModuleName...
74 is the name of a piece of documentation that you want to look at. You
75 may either give a descriptive name of the page (as in the case of
76 `perlfunc') the name of a module, either like `Term::Info',
77 `Term/Info', the partial name of a module, like `info', or
78 `makemaker', or the name of a program, like `perldoc'.
80 Any switches in the PERLDOC environment variable will be used before the
81 command line arguments.
89 unshift(@ARGV,shellwords($ENV{"PERLDOC"}));
91 getopts("mhtluv") || usage;
93 usage if $opt_h || $opt_h; # avoid -w warning
95 usage("only one of -t, -u, -m or -l") if $opt_t + $opt_u + $opt_m + $opt_l > 1;
97 if ($opt_t) { require Pod::Text; import Pod::Text; }
120 foreach $p (split(/\//, $file)){
121 if (($Is_VMS or $^O eq 'os2') and not scalar @p) {
122 # VMSish filesystems don't begin at '/'
128 } elsif (-f ("@p/$p")) {
134 while ($cip=readdir(DIR)) {
135 $cip =~ s/\.dir$// if $Is_VMS;
136 if (lc $cip eq $lcp){
142 return "" unless $found;
144 return "@p" if -f "@p";
147 return; # is not a file
151 my($recurse,$s,@dirs) = @_;
153 $s = VMS::Filespec::unixify($s) if $Is_VMS;
154 printf STDERR "looking for $s in @dirs\n" if $opt_v;
159 if (-f $s and containspod $s) {
162 for ($i=0;$i<@dirs;$i++) {
164 ($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
165 if (( $ret = minus_f_nocase "$dir/$s.pod")
166 or ( $ret = minus_f_nocase "$dir/$s.pm" and containspod($ret))
167 or ( $ret = minus_f_nocase "$dir/$s" and containspod($ret))
169 $ret = minus_f_nocase "$dir/$s.com" and containspod($ret))
170 or ( $ret = minus_f_nocase "$dir/pod/$s.pod")
171 or ( $ret = minus_f_nocase "$dir/pod/$s" and containspod($ret)))
176 my(@newdirs) = grep(-d,map("$dir/$_",grep(!/^\.\.?$/,readdir(D))));
178 @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
179 next unless @newdirs;
180 print STDERR "Also looking in @newdirs\n" if $opt_v;
181 push(@dirs,@newdirs);
189 print STDERR "Searching for $_\n" if $opt_v;
190 # We must look both in @INC for library modules and in PATH
191 # for executables, like h2xs or perldoc itself.
196 for ($i = 0; $trn = $ENV{'DCL$PATH'.$i}; $i++) {
197 push(@searchdirs,$trn);
200 push(@searchdirs, grep(-d, split(':', $ENV{'PATH'})));
202 @files= searchfor(0,$_,@searchdirs);
205 print STDERR "Found as @files\n" if $opt_v;
207 # no match, try recursive search
209 @searchdirs = grep(!/^\.$/,@INC);
212 @files= searchfor(1,$_,@searchdirs);
214 print STDERR "Loosely found as @files\n" if $opt_v;
216 print STDERR "No documentation found for '$_'\n";
223 exit ($Is_VMS ? 98962 : 1);
227 print join("\n", @found), "\n";
231 if( ! -t STDOUT ) { $opt_f = 1 }
234 $tmp = "/tmp/perldoc1.$$";
235 push @pagers, qw( more less pg view cat );
236 unshift @pagers, $ENV{PAGER} if $ENV{PAGER};
238 $tmp = 'Sys$Scratch:perldoc.tmp1_'.$$;
239 push @pagers, qw( most more less type/page );
241 unshift @pagers, $ENV{PERLDOC_PAGER} if $ENV{PERLDOC_PAGER};
244 foreach $pager (@pagers) {
245 my($sts) = system("$pager @found");
246 exit 0 if ($Is_VMS ? ($sts & 1) : !$sts);
248 exit $Is_VMS ? $sts : 1;
255 Pod::Text::pod2text($_,*TMP);
257 } elsif(not $opt_u) {
260 $rslt = `pod2man $_ | nroff -man | col -x`;
262 $rslt = `pod2man $_ | nroff -man`;
264 if ($Is_VMS) { $err = !($? % 2) || $rslt =~ /IVVERB/; }
266 print TMP $rslt unless $err;
270 if( $opt_u or $err or -z $tmp) {
275 $cut = $1 eq 'cut' if /^=(\w+)/;
289 foreach $pager (@pagers) {
290 $sts = system("$pager $tmp");
291 last if $Is_VMS && ($sts & 1);
296 1 while unlink($tmp); #Possibly pointless VMSism
304 perldoc - Look up Perl documentation in pod format.
308 B<perldoc> [B<-h>] [B<-v>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] PageName|ModuleName|ProgramName
312 I<perldoc> looks up a piece of documentation in .pod format that is embedded
313 in the perl installation tree or in a perl script, and displays it via
314 C<pod2man | nroff -man | $PAGER>. (In addition, if running under HP-UX,
315 C<col -x> will be used.) This is primarily used for the documentation for
316 the perl library modules.
318 Your system may also have man pages installed for those modules, in
319 which case you can probably just use the man(1) command.
327 Prints out a brief help message.
331 Describes search for the item in detail.
333 =item B<-t> text output
335 Display docs using plain text converter, instead of nroff. This may be faster,
336 but it won't look as nice.
338 =item B<-u> unformatted
340 Find docs only; skip reformatting by pod2*
344 Display the entire module: both code and unformatted pod documentation.
345 This may be useful if the docs don't explain a function in the detail
346 you need, and you'd like to inspect the code directly; perldoc will find
347 the file for you and simply hand it off for display.
349 =item B<-l> file name only
351 Display the file name of the module found.
353 =item B<PageName|ModuleName|ProgramName>
355 The item you want to look up. Nested modules (such as C<File::Basename>)
356 are specified either as C<File::Basename> or C<File/Basename>. You may also
357 give a descriptive name of a page, such as C<perlfunc>. You make also give a
358 partial or wrong-case name, such as "basename" for "File::Basename", but
359 this will be slower, if there is more then one page with the same partial
360 name, you will only get the first one.
366 Any switches in the C<PERLDOC> environment variable will be used before the
367 command line arguments. C<perldoc> also searches directories
368 specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
369 defined) and C<PATH> environment variables.
370 (The latter is so that embedded pods for executables, such as
371 C<perldoc> itself, are available.)
375 Kenneth Albanowski <kjahds@kjahds.com>
377 Minor updates by Andy Dougherty <doughera@lafcol.lafayette.edu>
382 # Version 1.11: Tue Dec 26 09:54:33 EST 1995
383 # Kenneth Albanowski <kjahds@kjahds.com>
384 # -added Charles Bailey's further VMS patches, and -u switch
385 # -added -t switch, with pod2text support
387 # Version 1.10: Thu Nov 9 07:23:47 EST 1995
388 # Kenneth Albanowski <kjahds@kjahds.com>
390 # -added better error recognition (on no found pages, just exit. On
391 # missing nroff/pod2man, just display raw pod.)
392 # -added recursive/case-insensitive matching (thanks, Andreas). This
393 # slows things down a bit, unfortunately. Give a precise name, and
396 # Version 1.01: Tue May 30 14:47:34 EDT 1995
397 # Andy Dougherty <doughera@lafcol.lafayette.edu>
398 # -added pod documentation.
399 # -added PATH searching.
400 # -added searching pod/ subdirectory (mainly to pick up perlfunc.pod
406 # Cache directories read during sloppy match
409 close OUT or die "Can't close $file: $!";
410 chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
411 exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';