If you have a manpage of the form

    NAME
        foo, bar, glarch - frizzle your frobnilzoot

Then "man foo", "man bar", and "man glarch" should all be
accessible.

For example, "man zip" produces

   NAME
      zip, zipcloak, zipnote, zipsplit - package and
compress (archive) files

However, you cannot type "man zipcloak" and get
anything.  This is bad enough for commands, but it's
horrible for library functions.  For example,
the pthread_key_create man page documents several
functions:

NAME
       pthread_key_create, pthread_key_delete,
pthread_setspecific, pthread_getspecific - management of
thread-specific data

However, those are not all accessible.  Try typing
"man pthread_getspecific" and you'll see what I mean.

This is a simple matter of automation.  I enclose
a trivial script I hacked up in a few minutes this
morning that identifies these problems.  It would be
equally easy to create one that fixes them.  This should
be part of your standard release preparation cycle.

thanks,

--tom

#!/usr/bin/perl

@mantree = qw{
    /usr/man
    /usr/X11R6/man
};

$| = 1;

foreach $tree (@mantree) {
    chdir($tree) || die "can't cd to $tree: $!";

    foreach $mandir ( grep { -d } <man*> ) {
        chdir("$tree/$mandir") || die "can't cd to
$tree/$mandir: $!";
        ($ext = $mandir) =~ s/^man//;
        for $page (@pages = <*.*>) {
            $page =~ s/\.gz$//;
            my ($name, $ext) = $page =~ /(\S+)\.(\S+)$/;
            next unless $name =~ /^[a-z]/;
            print "man $ext $name\n";
            open(MAN, "man $ext $name 2>&1 | col -b |")
                or die "cannot fork: $!";
            local $/ = '';
            while (<MAN>) {
                next unless /^NAME/m;
                s/-\n\s*//g;
                ($names) = /^(.*?) - /m;
                $names =~ s/^\s*//;
                $names =~ s/\s*$//;
                #@refs = $names =~ /([^,\s]+)/g;
                @refs = split(/,\s*/, $names);
                @refs = grep { uc($_) ne uc($name) } @refs;
                print "$name.$ext: @refs\n" if @refs;
                foreach $ref (@refs) {
                    $where = whereis("$ref($ext)");
                    print "$page refs $ref -> $where\n";
                }
                last;
            }
        }
    }

}

sub whereis {
    my $manref = shift;
    my ($page, $ext) = $manref =~ /(\S+)\((\S+)\)/;
    return $Seen{$page, $ext} if $Seen{$page, $ext};
    ($Seen{$page, $ext} = `man -w $ext '$page' 2>&1 `) =~
s/\n/ /g;
    if ($?) {
        $Seen{$page, $ext} =~ s/^/*** /;
        my $try_again = `man -w -a '$page' 2>&1 `;
        if (! $?) {
            $try_again =~ s/\n/ /g;
            $Seen{$page, $ext} =~ s/$/ (really $try_again)/;
        }
    }
    return $Seen{$page, $ext};
}