Bug 6044

Summary: Numerous Redhat manpages have incorrect references
Product: [Retired] Red Hat Linux Reporter: tchrist
Component: man-pagesAssignee: Trond Eivind Glomsrxd <teg>
Status: CLOSED RAWHIDE QA Contact:
Severity: medium Docs Contact:
Priority: medium    
Version: 6.0CC: tchrist
Target Milestone: ---   
Target Release: ---   
Hardware: i386   
OS: Linux   
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2001-03-13 15:42:48 UTC Type: ---
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:

Description tchrist 1999-10-18 12:12:02 UTC
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
Some of these are extremely annoying.  Please include an
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
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

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

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.


# chk_seealso - find missing or mis-referenced see also
# tchrist
@mantree = qw{

$| = 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 = <*.*>) {
            $orig = $_;
            $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/;
                @refs = /\S+\(\S+\)/g;
                # print "$page.$ext: @refs\n";
                for $ref (@refs) {
                    print "$page.$ext: $ref -> ",
whereis($ref), "\n";


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};

Comment 1 Trond Eivind Glomsrxd 2001-04-25 20:36:39 UTC
The situation has been improved, and the script handed over to QA. Thanks for
the script.