1. Overview
Manual pages, or simply man pages, are very useful for getting information about commands, library, and system calls in Linux. When we install a package using a package manager, the man pages are installed with the package. However, we may sometimes need to install man pages manually, especially for custom commands.
In this tutorial, we’ll discuss how to install man pages manually.
2. Installing man Pages Globally
We’ll install a man page for a command named hello, which greets the supplied person in the specified language. The name of the man page file is hello.1.
The number in the name of the man page file corresponds to which section the man page belongs to. 1 is for executable commands or shell commands, 2 is for system calls, 3 is for functions in program libraries, etc. The man page of the man command gives detailed information about the section numbers.
For installing a man page of a command, we must copy the corresponding man page file to one of the /usr/local/share/man/man1 or /usr/share/man/man1 directories. But, if the man page is for a function in a program library, the directory must be either the /usr/local/share/man/man3 or /usr/share/man/man3.
It’s a best practice to use /usr/local/share/man for manual installations without using a package manager. Therefore, we’ll prefer this directory, but let’s try to get help for the hello command before copying it:
$ man hello
No manual entry for hello
The result is expected as we haven’t installed the man page of hello. Let’s copy the man page file, hello.1:
$ sudo cp hello.1 /usr/local/share/man/man1
Copying a man page file to one of the man directories in /usr/local/share/man or /usr/share/man requires root privileges.
Having copied the man page file of hello, let’s run man hello once more:
$ man hello
HELLO(1) General Commands Manual HELLO(1)
NAME
hello - Greet a person
SYNOPSIS
hello [ -e | -i | -t ] person
DESCRIPTION
hello greets a person in the language specified by the option. If no
option is specified, the default language is English.
Options
-e Greet in English.
-i Greet in Indian.
-t Greet in Turkish.
SEE ALSO
bye(1)
BUGS
No known bugs
24 March 08 HELLO(1)
Therefore, we can reach the man page of hello now. This method is preferable when a man page must be reachable globally by all users.
3. Using MANPATH
Using the MANPATH environment variable is another option for setting a search path for man pages. Normally, it isn’t set, but once it’s set, it overrides the configuration file and automatic search path.
Before examining the MANPATH environment variable, let’s discuss the configuration file. The configuration file depends on the Linux distro. For example, it’s /etc/man_db.conf in Centos, but /etc/manpath.config in Debian. When we run the man command, man uses this configuration file, besides other factors, for finding the man pages at run time.
We can check the current man page search path using the manpath command:
$ manpath
/usr/local/share/man:/usr/share/man
The directories in the output of the manpath command are familiar. These are the directories we discussed in the previous section.
Returning to the MANPATH environment variable, we can append additional search directories for man pages using MANPATH. Let’s add the current working directory where hello.1 exists:
$ pwd
/home/centos/work/hello
$ ls hello.1
hello.1
$ export MANPATH=:/home/centos/work/hello
We added the current working directory to the search path using export MANPATH=:/home/centos/work/hello. Let’s check the output of manpath once more:
$ manpath
/usr/local/share/man:/usr/share/man:/home/centos/work/hello
We added /home/centos/work/hello to the search path. Running man hello displays the man page successfully as before.
We should add the export statement to .bash_profile to persist the changes.
While setting MANPATH, the colon at the beginning of the path is important. It appends the specified path to the existing search directories. Otherwise, we override the existing search directories:
$ manpath
/usr/local/share/man:/usr/share/man
$ export MANPATH=/home/centos/work/hello
$ manpath
/home/centos/work/hello
We can’t read the man pages of other commands in this case, for example, ls:
$ man ls
No manual entry for ls
4. The Relationship Between PATH and Search Paths
There is also a relation between the PATH environment variable and the search paths of man pages.
Let path_element be one of the path entries in the PATH environment variable. If there isn’t a line starting with MANPATH_MAP for a path_element in the configuration file /etc/man_db.conf or /etc/manpath.config, then the directories path_element/../man, path_element/man, path_element/../share/man, and path_element/share/man are also included in the search paths of man pages. manpath command doesn’t list these directories.
Let’s inspect this behavior with an example:
$ echo $PATH
/home/centos/.local/bin:/home/centos/bin:/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin
There are several path entries in our PATH environment variable. Let’s use the first one, /home/centos/.local/bin, which is the path_element in our case. Then, if we copy hello.1 in one of the man1 directories in /home/centos/.local/man, /home/centos/.local/bin/man, /home/centos/.local/share/man or /home/centos/.local/bin/share/man, then we can use the man page of hello. We don’t need to use the MANPATH environment variable:
$ echo $MANPATH
$ man hello
No manual entry for hello
$ mkdir -p /home/centos/.local/share/man/man1
$ cp hello.1 /home/centos/.local/share/man/man1
As the output of echo $MANPATH shows, MANPATH isn’t defined. We copied hello.1 to /home/centos/.local/share/man/man1. Running man hello displays the man page of hello successfully as before.
5. Conclusion
In this article, we discussed how to install man pages manually. Firstly, we learned how to install a man page globally by copying the corresponding man page file to the default search paths, /usr/local/share/man and /usr/share/man.
Then, we discussed the MANPATH environment variable. We saw that appending a path to this environment variable extends the search paths for man pages.
Finally, we learned the relationship between the entities in the PATH environment variable and the search paths of man pages.