Why does apropos and man -k omit or miss valid results?

Question

For example, if I enter the following command:

$ man -k compare

The diff command is missing from the results, however the test command is not. I get the same results using apropos as expected.

$ whereis diff
diff: /usr/bin/diff /usr/share/man/man1/diff.1.gz
$ whereis test
test: /usr/bin/test /usr/share/man/man1/test.1.gz

If I examine the short description of diff, it is the following:

NAME
       GNU diff - compare files line by line

As you can clearly see, "compare" is in the short description. Moreover, let's examine the long description too:

DESCRIPTION
       Compare FILES line by line.

And again, "Compare" appears in the description.

Now, let's examine the short description of test:

NAME
       test - check file types and compare values

Which is what I would expect. However, "compare" is missing from the description of test.

So, I'm not clear why man -k compare or apropos compare do not find diff. However I believe it has to do with the output of the whatis command:

$ whatis diff
diff (1)             - (unknown subject)
$ whatis test
test (1)             - check file types and compare values

Now the reason for this discrepancy may be due to the fact that the man page for diff has a name that consists of two words "GNU diff" rather than one, but I'm not sure.

Answer 1

This is a bug in the man pages of the GNU diffutils package. As you suspected, the problem is that they show “GNU diff” (etc.) rather than just “diff” as the program name. This causes the man program not to recognize the short description.

python3
>>> import dbm
>>> db = dbm.open('/var/cache/man/index.db')
>>> db['diff\0']
b'-\t1\t1\t1554725040\t0\tA\t-\t-\tgz\t\x00'
>>> db['cat\0']
b'-\t1\t1\t1567679920\t0\tA\t-\t-\tgz\tconcatenate files and print on the standard output\x00'

The bug was introduced somewhere after diffutils 3.3 and before diffutils 3.6. It was reported as bug #39760 and fixed in this commit or actually possibly this commit. The fixes aren't in a release yet, they will be in diffutils 3.8.