Debian Codegraph @

doc/source/cookbook/man-path.rst

raw
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: