Why is "man -k" so confused?

Solaris man uses a manual page index file called "windex" in
place of the old "whatis" file. You can build this index with

catman -w -M <man-page-directory>

But, in 2.1, this will result in numerous "line too long" messages
and a bogus windex file in /usr/share/man, and a core dump in
/usr/openwin/man. (In 2.2, catman works in /usr/share/man, but
says "line too long" in /usr/openwin/man). To add injury to
insult, "man" normally won't show you a man page if it can't find
the windex entry, even though the man page exists.

Makewhatis, or better, getNAME, still can't deal with all manual
pages from the net.

Solaris 8 man will look for the manual page the hard way if it
cannot find it in an existing "windex" file.

Starting with Solaris 7 manual pages are being converted to
SGML format; the formatting is now a lot slower as there's an
extra sgml2roff step in between.

But wait, there's more! To see the read(2) man page, you can't
just type "man 2 read" anymore - it has to be "man -s 2 read".
Or, alias man to this little script:

if [ $# -gt 1 -a "$1" -gt "0" ]; then
/bin/man -F -s $*
/bin/man -F $*

[an error occurred while processing this directive]