Mac OS X man command ignores $MANPATH (which sucks for HomeBrew installed commands)
I recently ran brew install coreutils to get the GNU versions of various commands such as ls. The first thing I noticed was that “man ls” did not display the man page for the GNU ls command. Even after setting the $MANPATH environment variable to include the relevant directory the man page was not displayed. Not even with “man -a ls” which should have shown all matching man pages in succession. The $MANPATH environment variable is completely ignored on Mac OS X as far as I can determine.
Similarly, editing /etc/manpaths and creating a file in /etc/manpaths.d containing the appropriate paths had no effect.
Only editing /etc/man.conf had any effect. Furthermore, it was not enough to simply add a MANPATH directive before any of the stock entries. Doing so did allow “man -a ls” to display the GNU ls man page but it was still not the primary man page. To make the GNU ls man page the primary I also had to add a MANPATH_MAP directive before any of the other MANPATH_MAP directives. Once I did that executing “man ls” and “man -w ls” shows the HomeBrew installed ls command man page as the primary documentation for that command.
Note that by default the man pages for HomeBrew commands that do not shadow standard commands are found and displayed by the man command. That is because a “MANPATH /usr/local/share/man” entry in /etc/man.conf is sufficient to find the associated man pages. It’s not clear whether that entry is present in a stock Mac OS X installation or is added by HomeBrew.
I love Mac OS X and would rather get a root canal than use MS Windows. But once in a while an annoyance like this one makes me wonder if anyone at Apple actually verifies that the software behaves as the documentations states.