Search code examples
macosshellemacspermissionsmanpage

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

I am trying to install a man page for a bash script on Mac OS X 10.9.5. The procedure that I tried to follow is summarised here: man page tutorial. I also summarise the steps that I tried below:

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

When trying man custom_command I receive the output No manual entry for custom_command. I also tried other installation methods mentioned in man page tutorial.

It is interesting to note that the steps above worked for the emacs console, i.e. I do get the correct manual when I type man custom_command. However, the command is not recognised by the autocomplete and I receive the following warning before I am able to read the manual: WARNING: terminal is not fully functional.

Any advice on how to resolve the issues above (i.e. both with the system terminal and the emacs console) would be appreciated.

Remark 1

For a reference, the man script that I am trying to install was taken from the tutorial and is restated below for a reference:

.\" Manpage for nuseradd.
.\" Contact [email protected] to correct errors or typos.
.TH man 8 "06 May 2010" "1.0" "nuseradd man page"
.SH NAME
nuseradd \- create a new LDAP user
.SH SYNOPSIS
nuseradd [USERNAME]
.SH DESCRIPTION
nuseradd is high level shell program for adding users to LDAP server.  On Debian, administrators should usually use nuseradd.debian(8) instead.
.SH OPTIONS
The nuseradd does not take any options. However, you can supply username.
.SH SEE ALSO
useradd(8), passwd(5), nuseradd.debian(8)
.SH BUGS
No known bugs.
.SH AUTHOR
Vivek Gite ([email protected])
Solution

  • 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