Bug 6044

This time I have analysed the manpages that you did provide
me with, and
discovered that a vast number of them had incorrect SEE ALSO
references.
Some of these are extremely annoying.  Please include an
automation
mechanism such as the one I provide you with below to find
out just what
is missing before you ship the release.

I did these two kinds of automated documentation checks ten
years ago
when I myself was putting together Unix release for
shipment.  I put
together the scripts to check them again in just a few
hacked up minutes.
It frightens me that we're actually backsliding so far.  You
have 1000
mistakes in your shipped system.  This is unprecedented.
Please, please fix them.

Yes, I realize that this is a lot of work, and that you
don't always have control over the packages.  I feel that
as a bundler and reseller, it's your responsibility to
produce a coherent and above all a PROFESSIONAL release, not
merely slapping together
a few thousand commands cranked out by zillions of random
Linux hackers.

I hope that the quick perl script I enclose below will help
you in this.  You may well care to edit it for your own
purposes.  Feel free.

In some cases, the problem is that the SEE ALSO is to the
wrong section, which this script attempts to identify.
For example:

mutt.1: curses(3) -> *** No entry for curses in section 3 of
the manual
mutt.1: dotlock(1) -> *** No entry for dotlock in section 1
of the manual
mutt.1: sendmail(1) -> *** No entry for sendmail in section
1 of the manual  (really /usr/man/man8/sendmail.8 )
mutt.1: smail(1) -> *** No entry for smail in section 1 of
the manual
mutt.1: mailcap(5) -> *** No entry for mailcap in section 5
of the manual  (really /usr/man/man4/mailcap.4 )

The case that spawned all this analysis is this one:

passwd.1: pam(8) -> *** No entry for pam in section 8 of the
manual
passwd.1: pam_chauthok(2) -> *** No entry for pam_chauthok
in section 2 of the manual

It as unbelievably frustrating to try to set up twenty
systems when one of the most critical components, the
passwd authentication, is incompletely and inaccurately
documented.

All I want is a coherent, self-contained, and documented
system.

The program below was what I used to figure this out.
You have approximately ONE THOUSAND mistakes in your
"SEE ALSO" sections, and about 6x that many correct entries.
I will omit the thousand errors.  You can run the program
yourself and find them.  Hack and use at will.

--tom

#!/usr/bin/perl
# chk_seealso - find missing or mis-referenced see also
# tchrist
@mantree = qw{
    /usr/man
    /usr/X11/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 (@pages = <*.*>) {
            s/\.gz$//;
            $orig = $_;
            s/\.${ext}\w*$//;
            $orig{$_} = $orig;
        }
        for $page (@pages) {
            # print "man $ext $page\n";
            open(MAN, "man $ext $page 2>&1 | col -b |")
                or die "cannot fork: $!";
            local $/ = '';
            while (<MAN>) {
                next unless /^SEE ALSO/;
                s/-\n\s*//g;
                @refs = /\S+\(\S+\)/g;
                # print "$page.$ext: @refs\n";
                for $ref (@refs) {
                    print "$page.$ext: $ref -> ",
whereis($ref), "\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};
}