| 1 |
.. _man-path: |
| 2 |
|
| 3 |
Handle man pages search path |
| 4 |
============================ |
| 5 |
|
| 6 |
Man pages (manual pages), read with :command:`man` command, are stored in a |
| 7 |
structured directory hierarchy under predefined locations. They are typically |
| 8 |
stored within ``/usr/share/man`` and software-specific *man* directories. |
| 9 |
|
| 10 |
:command:`man` searches for man pages the following way: |
| 11 |
|
| 12 |
* if :envvar:`MANPATH` environment variable is set, man pages are only |
| 13 |
searched in the directories specified in it |
| 14 |
* if :envvar:`MANPATH` is not set, :command:`man` determines the hierarchy |
| 15 |
search path using information gained from the ``man-db`` configuration |
| 16 |
|
| 17 |
See `SEARCH PATH section`_ of ``manpath(5)`` man page to learn how ``man-db`` |
| 18 |
computes the default search path. |
| 19 |
|
| 20 |
.. _SEARCH PATH section: https://man7.org/linux/man-pages/man5/manpath.5.html#SEARCH_PATH |
| 21 |
|
| 22 |
The :command:`manpath` command can be used to observe the currently active |
| 23 |
search path: |
| 24 |
|
| 25 |
.. parsed-literal:: |
| 26 |
|
| 27 |
:ps:`$` manpath |
| 28 |
/usr/local/share/man:/usr/share/man |
| 29 |
:ps:`$` export MANPATH=/usr/share/man |
| 30 |
:ps:`$` manpath |
| 31 |
manpath: warning: $MANPATH set, ignoring /etc/man_db.conf |
| 32 |
/usr/share/man |
| 33 |
|
| 34 |
Systems usually do not define :envvar:`MANPATH` by default and rely on |
| 35 |
``man-db`` configuration. On such systems, if a modulefile adds a specific |
| 36 |
man page directory to :envvar:`MANPATH`, :command:`man` will not be able to |
| 37 |
find system regular man pages anymore. |
| 38 |
|
| 39 |
.. parsed-literal:: |
| 40 |
|
| 41 |
:ps:`$` man --where ls |
| 42 |
/usr/share/man/man1/ls.1.gz |
| 43 |
:ps:`$` module show foo/1.0 |
| 44 |
------------------------------------------------------------------- |
| 45 |
:sgrhi:`/path/to/modulefiles/foo/1.0`: |
| 46 |
|
| 47 |
:sgrcm:`append-path` PATH /path/to/foo-1.0/bin |
| 48 |
:sgrcm:`append-path` MANPATH /path/to/foo-1.0/man |
| 49 |
------------------------------------------------------------------- |
| 50 |
:ps:`$` module load foo/1.0 |
| 51 |
:ps:`$` man --where ls |
| 52 |
No manual entry for ls |
| 53 |
|
| 54 |
To retain access to the system man pages when modulefiles modify the |
| 55 |
:envvar:`MANPATH`, the default search paths must be added into |
| 56 |
:envvar:`MANPATH`. This can be done by appending a colon (``:``) to the end of |
| 57 |
the :envvar:`MANPATH` value, which instructs the system to include its default |
| 58 |
man page directories. |
| 59 |
|
| 60 |
.. parsed-literal:: |
| 61 |
|
| 62 |
:ps:`$` manpath |
| 63 |
manpath: warning: $MANPATH set, ignoring /etc/man_db.conf |
| 64 |
/path/to/foo-1.0/man |
| 65 |
:ps:`$` man --where ls |
| 66 |
No manual entry for ls |
| 67 |
:ps:`$` module append-path MANPATH : |
| 68 |
:ps:`$` man --where ls |
| 69 |
/usr/share/man/man1/ls.1.gz |
| 70 |
|
| 71 |
If your modulefiles modify :envvar:`MANPATH`, it is recommended to initialize |
| 72 |
this environment variable with a single colon (``:``) during Modules startup. |
| 73 |
|
| 74 |
To do this on Modules 5.7 or any newer version, add the following line to the |
| 75 |
``initrc`` configuration file (typically located in |
| 76 |
``/etc/environment-modules``): |
| 77 |
|
| 78 |
.. code-block:: |
| 79 |
|
| 80 |
module config init_envvars MANPATH= |
| 81 |
|
| 82 |
With this configuration, the ``MANPATH`` environment variable will be |
| 83 |
initialized to an empty string right before its first modification. As a |
| 84 |
result a leading or finishing colon character will be set the first time a |
| 85 |
path entry is added to ``MANPATH``. |
| 86 |
|
| 87 |
With older versions of Modules, add the following line to the ``initrc`` |
| 88 |
configuration file: |
| 89 |
|
| 90 |
.. code-block:: tcl |
| 91 |
|
| 92 |
append-path MANPATH : |
| 93 |
|
| 94 |
.. vim:set tabstop=2 shiftwidth=2 expandtab autoindent: |