[inseparable changes from patch to perl 5.004_04]perl-5.004_04

[editor's note: this one imported like a charm!]

 TESTS  -

Subject: Improve pragma/locale test 102 - and don't fail, just warn
From: Jarkko Hietaniemi <jhi@anna.in-berlin.de>
Files: t/pragma/locale.t

Subject: Invalid test output in t/op/taint.t in trial 1
From: Dan Sugalski <sugalsd@lbcc.cc.or.us>
Files: t/op/taint.t

    t/op/taint.t prints out invalid ok messages for tests it skips.
    Rather than printing "ok 136" it prints "136 ok".
    
    p5p-msgid: 3.0.3.32.19970919160918.00857a50@stargate.lbcc.cc.or.us

 UTILITIES  -

Subject: Perldoc tiny patch to avoid $0
From: Ilya Zakharevich <ilya@math.ohio-state.edu>
Files: utils/perldoc.PL
Msg-ID: 199709122141.RAA16846@monk.mps.ohio-state.edu

    (applied based on p5p patch as commit 0b166b6635cf199f072db516b2a523ee659394d5)

Subject: h2ph broken in 5.004_02
From: David Mazieres <dm@reeducation-labor.lcs.mit.edu>
Files: utils/h2ph.PL
Msg-ID: 199708201700.KAA02621@www.chapin.edu

    (applied based on p5p patch as commit 4a8e146e38ec2045f1f817a7cb578e1b1f80f39f)

Subject: add key_t caddr_t to h2ph
From: Tony Sanders <sanders@bsdi.com>
Files: eg/sysvipc/ipcsem utils/h2ph.PL
Msg-ID: 199708272301.RAA12803@austin.bsdi.com

    (applied based on p5p patch as commit 0806a92ffc3a74ca70aa81051cdf2a306cd0a8af)

Subject: perldoc search ., lib and blib/* if -f 'Makefile.PL'
From: Tim Bunce <Tim.Bunce@ig.co.uk>
Files: utils/perldoc.PL

    Subject: perldoc finds wrong pod2man
    
    (from perldoc source)
    
        # We must look both in @INC for library modules and in PATH
        # for executables, like h2xs or perldoc itself.
    
    Unfortunately, searching PATH for installed perl executables like
    pod2man is INCORRECT.  perldoc should start by searching the
    directory it was executed from, which might not be in the PATH
    at all.
    
    Credited: Joseph "Moof-in'" Hall <joseph@cscaper.com>
    
    p5p-msgid: 199708251732.KAA19299@gadget.cscaper.com

Subject: 5.004m4t1: perlbug: NIS domainname gets into wrong places
From: Andreas J. Koenig <koenig@anna.mind.de>
Files: utils/perlbug.PL
Msg-ID: sfcg1qy38as.fsf@anna.in-berlin.de

    (applied based on p5p patch as commit 41f926b844140b7f7eaa9302113e45df3a9f9ff4)

Subject: add better local patch info to perlbug
From: Tim Bunce <Tim.Bunce@ig.co.uk>
Files: utils/perlbug.PL

Subject: perldoc - suggest modules if requested module not found
From: Anthony David <adavid@netinfo.com.au>
Files: utils/perldoc.PL

    private-msgid: 3439CD83.6969@netinfo.com.au

Subject: perldoc mail::foo tries to read binary /usr/ucb/mail
From: Tim Bunce <Tim.Bunce@ig.co.uk>
Files: utils/perldoc.PL

    Subject: perldoc weirdness
    
    perldoc mail::imap yields:
    
    {joseph}:79% perldoc mail::foo
    can't open /usr/ucb/mail: Permission denied at ./pod2man line 362.
    
    Credited: Joseph "Moof-in'" Hall <joseph@cscaper.com>
    
    p5p-msgid: 199710082014.NAA00808@gadget.cscaper.com

Subject: perldoc -f setpwent (for example) returns no descriptive text
From: Tim Bunce <Tim.Bunce@ig.co.uk>
Files: utils/perldoc.PL

Subject: perldoc diffs: don't search auto - much faster
From: "Joseph N. Hall" <joseph@5sigma.com>
Files: utils/perldoc.PL
Msg-ID: MailDrop1.2d7dPPC.971012211957@screechy.cscaper.com

    (applied based on p5p patch as commit 62b753c6ae4ab9bf22fbb6ec7ceac820bcef8fe4)

1 files changed, 117 insertions, 59 deletions

diff --git a/utils/perldoc.PL b/utils/perldoc.PL
index 38ea9ee5ca..d223a9aaf9 100644
--- a/utils/perldoc.PL
+++ b/utils/perldoc.PL
@@ -45,10 +45,11 @@ print OUT <<'!NO!SUBS!';
 # the perl manuals, though it too is written in perl.
 
 if(@ARGV<1) {
-        $0 =~ s,.*/,,;
+	$me = $0;		# Editing $0 is unportable
+	$me =~ s,.*/,,;
 	die <<EOF;
-Usage: $0 [-h] [-v] [-t] [-u] [-m] [-l] PageName|ModuleName|ProgramName
-       $0 -f PerlFunc
+Usage: $me [-h] [-v] [-t] [-u] [-m] [-l] PageName|ModuleName|ProgramName
+       $me -f PerlFunc
 
 We suggest you use "perldoc perldoc" to get aquainted 
 with the system.
@@ -58,6 +59,9 @@ EOF
 use Getopt::Std;
 use Config '%Config';
 
+@global_found = ();
+$global_target = "";
+
 $Is_VMS = $^O eq 'VMS';
 $Is_MSWin32 = $^O eq 'MSWin32';
 
@@ -118,36 +122,60 @@ if ($opt_f) {
    @pages = @ARGV;
 }
 
+# Does this look like a module or extension directory?
+if (-f "Makefile.PL") {
+	# Add ., lib and blib/* libs to @INC (if they exist)
+	unshift(@INC, '.');
+	unshift(@INC, 'lib') if -d 'lib';
+	require ExtUtils::testlib;
+}
+
 
 
 sub containspod {
-	my($file) = @_;
-	local($_);
-	open(TEST,"<$file");
-	while(<TEST>) {
-		if(/^=head/) {
-			close(TEST);
-			return 1;
-		}
+    my($file, $readit) = @_;
+    return 1 if !$readit && $file =~ /\.pod$/i;
+    local($_);
+    open(TEST,"<$file");
+    while(<TEST>) {
+	if(/^=head/) {
+	    close(TEST);
+	    return 1;
 	}
-	close(TEST);
-	return 0;
+    }
+    close(TEST);
+    return 0;
 }
 
 sub minus_f_nocase {
      my($file) = @_;
      # on a case-forgiving file system we can simply use -f $file
      if ($Is_VMS or $Is_MSWin32 or $^O eq 'os2') {
-        return ( -f $file ) ? $file : '';
+        return $file if -f $file and -r _;
+	warn "Ignored $file: unreadable\n" unless -r _;
+	return '';
      }
      local *DIR;
      local($")="/";
      my(@p,$p,$cip);
      foreach $p (split(/\//, $file)){
- 	if (-d ("@p/$p")){
+	my $try = "@p/$p";
+	stat $try;
+ 	if (-d _){
  	    push @p, $p;
- 	} elsif (-f ("@p/$p")) {
- 	    return "@p/$p";
+	    if ( $p eq $global_target) {
+		$tmp_path = join ('/', @p);
+		my $path_f = 0;
+		for (@global_found) {
+		    $path_f = 1 if $_ eq $tmp_path;
+		}
+		push (@global_found, $tmp_path) unless $path_f;
+		print STDERR "Found as @p but directory\n" if $opt_v;
+	    }
+ 	} elsif (-f _ && -r _) {
+ 	    return $try;
+ 	} elsif (-f _) {
+	    warn "Ignored $try: unreadable\n";
  	} else {
  	    my $found=0;
  	    my $lcp = lc $p;
@@ -161,49 +189,64 @@ sub minus_f_nocase {
  	    closedir DIR;
  	    return "" unless $found;
  	    push @p, $cip;
- 	    return "@p" if -f "@p";
+ 	    return "@p" if -f "@p" and -r _;
+	    warn "Ignored $file: unreadable\n" if -f _;
  	}
      }
      return; # is not a file
- }
+}
  
-  sub searchfor {
-  	my($recurse,$s,@dirs) = @_;
-  	$s =~ s!::!/!g;
-  	$s = VMS::Filespec::unixify($s) if $Is_VMS;
-	return $s if -f $s && containspod($s);
-  	printf STDERR "looking for $s in @dirs\n" if $opt_v;
- 	my $ret;
- 	my $i;
- 	my $dir;
-  	for ($i=0;$i<@dirs;$i++) {
-  		$dir = $dirs[$i];
-  		($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
- 	    if ((    $ret = minus_f_nocase "$dir/$s.pod")
- 		or ( $ret = minus_f_nocase "$dir/$s.pm"  and containspod($ret))
- 		or ( $ret = minus_f_nocase "$dir/$s"     and containspod($ret))
-  		or ( $Is_VMS and 
- 		     $ret = minus_f_nocase "$dir/$s.com" and containspod($ret))
+
+sub check_file {
+    my($file) = @_;
+    return minus_f_nocase($file) && containspod($file) ? $file : "";
+}
+
+
+sub searchfor {
+    my($recurse,$s,@dirs) = @_;
+    $s =~ s!::!/!g;
+    $s = VMS::Filespec::unixify($s) if $Is_VMS;
+    return $s if -f $s && containspod($s);
+    printf STDERR "Looking for $s in @dirs\n" if $opt_v;
+    my $ret;
+    my $i;
+    my $dir;
+    $global_target = (split('/', $s))[-1];
+    for ($i=0; $i<@dirs; $i++) {
+	$dir = $dirs[$i];
+	($dir = VMS::Filespec::unixpath($dir)) =~ s!/$!! if $Is_VMS;
+	if (       ( $ret = check_file "$dir/$s.pod")
+		or ( $ret = check_file "$dir/$s.pm")
+		or ( $ret = check_file "$dir/$s")
+		or ( $Is_VMS and
+		     $ret = check_file "$dir/$s.com")
 		or ( $^O eq 'os2' and 
- 		     $ret = minus_f_nocase "$dir/$s.cmd" and containspod($ret))
+		     $ret = check_file "$dir/$s.cmd")
 		or ( ($Is_MSWin32 or $^O eq 'os2') and 
- 		     $ret = minus_f_nocase "$dir/$s.bat" and containspod($ret))
- 		or ( $ret = minus_f_nocase "$dir/pod/$s.pod")
- 		or ( $ret = minus_f_nocase "$dir/pod/$s" and containspod($ret)))
- 		{ return $ret; }
- 		
- 		if($recurse) {
-			opendir(D,$dir);
-			my(@newdirs) = grep(-d,map("$dir/$_",grep(!/^\.\.?$/,readdir(D))));
-			closedir(D);
-			@newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
-			next unless @newdirs;
-			print STDERR "Also looking in @newdirs\n" if $opt_v;
-			push(@dirs,@newdirs);
- 		}
- 	}
-  	return ();
-  }
+		     $ret = check_file "$dir/$s.bat")
+		or ( $ret = check_file "$dir/pod/$s.pod")
+		or ( $ret = check_file "$dir/pod/$s")
+	) {
+	    return $ret;
+	}
+	
+	if ($recurse) {
+	    opendir(D,$dir);
+	    my @newdirs = map "$dir/$_", grep {
+		not /^\.\.?$/ and
+		not /^auto$/  and   # save time! don't search auto dirs
+		-d  "$dir/$_"
+	    } readdir D;
+	    closedir(D);
+	    next unless @newdirs;
+	    @newdirs = map((s/.dir$//,$_)[1],@newdirs) if $Is_VMS;
+	    print STDERR "Also looking in @newdirs\n" if $opt_v;
+	    push(@dirs,@newdirs);
+	}
+    }
+    return ();
+}
 
 
 foreach (@pages) {
@@ -230,12 +273,24 @@ foreach (@pages) {
 		
 		@searchdirs = grep(!/^\.$/,@INC);
 		
-		
 		@files= searchfor(1,$_,@searchdirs);
 		if( @files ) {
 			print STDERR "Loosely found as @files\n" if $opt_v;
 		} else {
-			print STDERR "No documentation found for '$_'\n";
+			print STDERR "No documentation found for \"$_\".\n";
+			if (@global_found) {
+			    print STDERR "However, try\n";
+			    my $dir = $file = "";
+			    for $dir (@global_found) {
+				opendir(DIR, $dir) or die "$!";
+				while ($file = readdir(DIR)) {
+				    next if ($file =~ /^\./);
+				    $file =~ s/\.(pm|pod)$//;
+				    print STDERR "\tperldoc $_\::$file\n";
+				}
+				closedir DIR;
+			    }
+			}
 		}
 	}
 	push(@found,@files);
@@ -290,13 +345,16 @@ if ($opt_f) {
 
    # Look for our function
    my $found = 0;
+   my @pod;
    while (<PFUNC>) {
        if (/^=item\s+\Q$opt_f\E\b/o)  {
-	   $found++;
+	   $found = 1;
        } elsif (/^=item/) {
-	   last if $found;
+	   last if $found > 1;
        }
-       push(@pod, $_) if $found;
+       next unless $found;
+       push @pod, $_;
+       ++$found if /^\w/;	# found descriptive text
    }
    if (@pod) {
        if ($opt_t) {