Installing man Pages Manually

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.