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}; }
The situation has been improved, and the script handed over to QA. Thanks for the script.