/usr/man symlink breaks apropos man -k due to fsstnd

[Ian! D. Allen]

In the old days, man pages were stored under /usr/man. Now, they are
stored under /usr/share/man. Ubuntu systems no longer have a /usr/man,
so all our really old scripts and reflexes that look under /usr/man fail
unless you think to add the helpful symlink "ln -s share/man /usr/man".

But making that helpful symlink breaks "apropos" and "man -k" because
in /etc/manpath.config are these two different locations for the "mandb"
index database:

    MANDB_MAP /usr/man /var/cache/man/fsstnd
    MANDB_MAP /usr/share/man /var/cache/man

If you add the symlink for /usr/man, then the index.db file created
by "mandb" ends up under a sub-directory /var/cache/man/fsstnd where
"apropos" and "man -k" can't find it.

Of course you can add another helpful symlink "ln -s fsstnd/index.db
/var/cache/index.db" to work-around the "apropos" problem, or you can
set your "MANPATH=/usr/man", but surely it doesn't need to be a problem
in the first place.

1. Please make "apropos" and "man -k" smarter. Either they could look
in both /var/cache/man and /var/cache/man/fsstnd, or else "mandb" could
resolve the symlink /usr/man to its absolute version /usr/share/man before
looking it up in the manpath.config file and thus not create the unhelpful
"/fsstnd" sub-directory that breaks "apropos".

2. The man page for "mandb" and the manpath.config file make no
mention of the reason for the extra "/fsstnd" sub-directory. The
manpath.config file says the "FHS compliant" index.db location should
be /var/cache/man/index.db and the "FSSTND compliant" location is under
/var/catman Either remove the mysterious "/fsstnd" or explain it.

ProblemType: Bug
DistroRelease: Ubuntu 20.04
Package: man-db 2.9.1-1
ProcVersionSignature: Ubuntu 5.8.0-63.71~20.04.1-generic 5.8.18
Uname: Linux 5.8.0-63-generic x86_64
ApportVersion: 2.20.11-0ubuntu27.18
Architecture: amd64
CasperMD5CheckResult: skip
Date: Mon Aug 30 04:37:46 2021
EcryptfsInUse: Yes
InstallationDate: Installed on 2020-10-07 (326 days ago)
InstallationMedia: Lubuntu 20.04.1 LTS "Focal Fossa" - Release amd64 (20200731)
SourcePackage: man-db
UpgradeStatus: No upgrade log present (probably fresh install)

[Colin Watson (cjwatson)]

This is a bit perplexing, because the transition to /usr/share/man completed before Ubuntu even existed; I think it even predates my taking over maintainership of man-db 20 years ago or so. Is it really easier to go through all of this mess with symlinks rather than just updating a few extremely old scripts? I know reflexes can be harder, but still, it's been 20 years.

We can perhaps improve some documentation, but I don't currently think it's going to be worth the development effort to improve handling of the case where somebody has manually inserted a /usr/man symlink.

[Ian! D. Allen (idallen)]

If you could at least document what "/fsstnd" is (when the mandb man page says FSSTND should use /var/catman not /fsstnd), and why /usr/man and /usr/share/man are different and must look in different places in the MANDB_MAP, then maybe the current behaviour wouldn't look like a bug but a feature. I don't know why /usr/man and /usr/share/man aren't exactly the same in the manpath.config file; any documentation help you can provide would make the current odd behaviour seem less odd.