Bug 6044 - Numerous Redhat manpages have incorrect references
Numerous Redhat manpages have incorrect references
Status: CLOSED RAWHIDE
Product: Red Hat Linux
Classification: Retired
Component: man-pages (Show other bugs)
6.0
i386 Linux
medium Severity medium
: ---
: ---
Assigned To: Trond Eivind Glomsrxd
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 1999-10-18 08:12 EDT by tchrist
Modified: 2008-05-01 11:37 EDT (History)
1 user (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2001-03-13 10:42:48 EST
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description tchrist 1999-10-18 08:12:02 EDT
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@perl.com
@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};
}
Comment 1 Trond Eivind Glomsrxd 2001-04-25 16:36:39 EDT
The situation has been improved, and the script handed over to QA. Thanks for
the script.

Note You need to log in before you can comment on or make changes to this bug.