Handle man pages search path¶

Man pages (manual pages), read with man command, are stored in a structured directory hierarchy under predefined locations. They are typically stored within /usr/share/man and software-specific man directories.

man searches for man pages the following way:

if MANPATH environment variable is set, man pages are only searched in the directories specified in it
if MANPATH is not set, man determines the hierarchy search path using information gained from the man-db configuration

See SEARCH PATH section of manpath(5) man page to learn how man-db computes the default search path.

The manpath command can be used to observe the currently active search path:

$ manpath
/usr/local/share/man:/usr/share/man
$ export MANPATH=/usr/share/man
$ manpath
manpath: warning: $MANPATH set, ignoring /etc/man_db.conf
/usr/share/man

Systems usually do not define MANPATH by default and rely on man-db configuration. On such systems, if a modulefile adds a specific man page directory to MANPATH, man will not be able to find system regular man pages anymore.

$ man --where ls
/usr/share/man/man1/ls.1.gz
$ module show foo/1.0
-------------------------------------------------------------------
/path/to/modulefiles/foo/1.0:

append-path     PATH /path/to/foo-1.0/bin
append-path     MANPATH /path/to/foo-1.0/man
-------------------------------------------------------------------
$ module load foo/1.0
$ man --where ls
No manual entry for ls

To retain access to the system man pages when modulefiles modify the MANPATH, the default search paths must be added into MANPATH. This can be done by appending a colon (:) to the end of the MANPATH value, which instructs the system to include its default man page directories.

$ manpath
manpath: warning: $MANPATH set, ignoring /etc/man_db.conf
/path/to/foo-1.0/man
$ man --where ls
No manual entry for ls
$ module append-path MANPATH :
$ man --where ls
/usr/share/man/man1/ls.1.gz

If your modulefiles modify MANPATH, it is recommended to initialize this environment variable with a single colon (:) during Modules startup.

To do this on Modules 5.7 or any newer version, add the following line to the initrc configuration file (typically located in /etc/environment-modules):

module config init_envvars MANPATH=

With this configuration, the MANPATH environment variable will be initialized to an empty string right before its first modification. As a result a leading or finishing colon character will be set the first time a path entry is added to MANPATH.

With older versions of Modules, add the following line to the initrc configuration file:

append-path MANPATH :