How to install custom man (manual) pages on mac os x

First of all you may want to check if the man page your are trying to install is properly formatted and can be opened by man command. To do this pass the path to the man file to man command. It must contain a slash in order to be recognized as a path, for example:

man /usr/local/man/man1/custom_command.1

Then you should make sure the path you are installing your man page to is on the search list of man command. In order to find the man page its path must be either:

• specified with -M option to the man command
• set in the environmental variable MANPATH
• listed in its config file (/private/etc/man.conf on OS X) under MANPATH statement or under MANPATH_MAP statement (which applies only to locations in your PATH environmental variable)
• located in the location relative to where binary is installed, i.e.: if binary is installed in path/bin the man page is searched for in path/man, path/cat and path/bin/man, path/bin/cat
• listed in files added in /private/etc/manpaths.d/ directory

The name of the man page file must be same as command name with optional section number. It may be gzipped.

To see where man will search for your custom_command man page run

man -d custom_command

OS X user command man pages are typically created in:

/usr/local/share/man/man1

If you prefer to create man pages in a different directory edit:

/private/etc/man.conf

Then add the new path to MANPATH_MAP, for example:

MANPATH_MAP     /usr/local/bin         /usr/local/man

To have man search a non-default path with a default fallback (/usr/local/share/man):

MANPATH         /usr/local/man      
MANPATH         /usr/local/share/man 
MANPATH_MAP     /usr/local/bin         /usr/local/share/man