When to use man and man -k to check manual pages?

Question

When should one use man and when man -k to check man pages? Whenever I'd like to check a man page I get confused with which one I should. Should I use this: man -k xyz or this: man xyz.

Some man pages are not found when we search using man, however that same page is found by man -k .

So please give an explanation when I should use man xyz or man -k xyz.

Solution

Doing a man man shows you what the -k switch does to man.

Using the -k switch

man -k printf
       Search  the  short descriptions and manual page names for the keyword 
       printf as regular expression.  Print out any matches.  Equivalent
       to apropos -r printf.

The tool, apropos mentioned above, searches through index files, looking at both the names of the man pages as well as a short description of each.

man apropos

Each manual page has a short description available within it.
apropos searches the descriptions for instances of keyword.

You can compare the 2 commands output, to convince yourself that they're doing the same things like so:

$ diff <(man -k printf) <(apropos -r printf)
$

Just man

Doing just a man xyz will search for a man page in the locations defined when you do a man -w.

Example

$ man -w
/usr/local/share/man:/usr/share/man

So when I type man xyz the man command will search through those directories, looking for a man page that corresponds to xyz.

Bottom line?

So man xyz is looking for man pages that correspond to the name xyz, while man -k xyz is looking for the string, "xyz" in both the names of the man pages along with the short description for each man page.

Comments

[Cristian Ciupitu]

I suggest running man man and checking out what -k does.