manual/man-db/original/man5/manpath.man5

   1 .\" Man page for format of the manpath.config data file
   2 .\"
   3 .\" Copyright (C) 1994, 1995 Graeme W. Wilford. (Wilf.)
   4 .\" Copyright (C) 2001-2019 Colin Watson.
   5 .\"
   6 .\" You may distribute under the terms of the GNU General Public
   7 .\" License as specified in the file COPYING that comes with the
   8 .\" man-db distribution.
   9 .\"
  10 .\" Sat Oct 29 13:09:31 GMT 1994  Wilf. (G.Wilford@ee.surrey.ac.uk)
  11 .\"
  12 .pc
  13 .TH MANPATH 5 "%date%" "%version%" "%manpath_config_file%"
  14 .SH NAME
  15 manpath \- format of the %manpath_config_file% file
  16 .SH DESCRIPTION
  17 The manpath configuration file is used by the manual page utilities
  18 to assess users' manpaths at run time, to indicate which manual page
  19 hierarchies (manpaths) are to be treated as system hierarchies and to
  20 assign them directories to be used for storing cat files.
  21
  22 If the environment variable
  23 .RB $ MANPATH
  24 is already set, the information contained within %manpath_config_file% will
  25 not override it.
  26 .SH SEARCH PATH
  27 By default, man-db examines the user's
  28 .RB $ PATH .
  29 For each
  30 .I path_element
  31 found there,
  32 it adds
  33 .I manpath_element
  34 to the search path.
  35
  36 If there is no
  37 .B MANPATH_MAP
  38 line in the configuration file for a given
  39 .IR path_element ,
  40 then it adds all of
  41 .IR path_element/../man ,
  42 .IR path_element/man ,
  43 .IR path_element/../share/man ,
  44 and
  45 .IR path_element/share/man
  46 that exist as directories to the search path.
  47
  48 It then adds any
  49 .B MANDATORY_MANPATH
  50 entries from the configuration file to the search path.
  51
  52 Finally, if the
  53 .B \-\-systems
  54 option is used or the
  55 .RB $ SYSTEM
  56 environment variable is set, then that should consist of a sequence of
  57 operating system names separated by commas or colons.
  58 This acts as a template, expanding the search path once more to allow access
  59 to other operating systems' manual pages: for each system name, man-db looks
  60 for that name as a subdirectory of each entry in the search path, and adds
  61 it to the final search path if it exists.
  62 A system name of
  63 .B man
  64 inserts the normal search path without subdirectories.
  65 For example, if the search path would otherwise have been
  66 .IR /usr/share/man:/usr/local/man ,
  67 and
  68 .RB $ SYSTEM
  69 is set to
  70 .IR newOS:man ,
  71 then the final search path will be
  72 .IR /usr/share/man/newOS:/usr/share/man:/usr/local/man/newOS:/usr/local/man .
  73
  74 The
  75 .RB $ MANPATH
  76 environment variable overrides man-db's default manual page search paths.
  77 Most users should not need to set it.
  78 Its syntax is similar to the
  79 .RB $ PATH
  80 environment variable: it consists of a sequence of directory names separated
  81 by colons.
  82 It overrides the default search path described above.
  83
  84 If the value of
  85 .RB $ MANPATH
  86 starts with a colon, then the default search path is added at its start.
  87 If the value of
  88 .RB $ MANPATH
  89 ends with a colon, then the default search path is added at its end.
  90 If the value of
  91 .RB $ MANPATH
  92 contains a double colon
  93 .RB ( :: ),
  94 then the default search path is inserted in the middle of the value, between
  95 the two colons.
  96 .SH FORMAT
  97 The following field types are currently recognised:
  98 .TP
  99 .BI # \ comment
 100 Blank lines or those beginning with a
 101 .B #
 102 will be treated as comments and ignored.
 103 .TP
 104 .BI MANDATORY_MANPATH \ manpath_element
 105 Lines of this form indicate manpaths that every automatically generated
 106 .RB $ MANPATH
 107 should contain.
 108 This will typically include
 109 .IR /usr/man .
 110 .TP
 111 .BI MANPATH_MAP \ path_element\ manpath_element
 112 Lines of this form set up
 113 .RB $ PATH
 114 to
 115 .RB $ MANPATH
 116 mappings.
 117 For each
 118 .I path_element
 119 found in the user's
 120 .RB $ PATH ,
 121 .I manpath_element
 122 will be added to the
 123 .RB $ MANPATH .
 124 .TP
 125 \fBMANDB_MAP \fImanpath_element \fR\|[\| \fIcatpath_element\fR \|]
 126 Lines of this form indicate which manpaths are to be treated as system
 127 manpaths, and optionally where their cat files should be stored.
 128 This field type is particularly important if
 129 .B man
 130 is a setuid program, as (when in the system configuration file
 131 %manpath_config_file% rather than the per-user configuration file .manpath)
 132 it indicates which manual page hierarchies to access as the setuid user and
 133 which as the invoking user.
 134
 135 The system manual page hierarchies are usually those stored under
 136 .I /usr
 137 such as
 138 .IR /usr/man ,
 139 .I /usr/local/man
 140 and
 141 .IR /usr/X11R6/man .
 142
 143 If cat pages from a particular
 144 .I manpath_element
 145 are not to be stored or are to be stored in the traditional location,
 146 .I catpath_element
 147 may be omitted.
 148
 149 Traditional cat placement would be impossible for read only mounted manual
 150 page hierarchies and because of this it is possible to specify any valid
 151 directory hierarchy for their storage.
 152 To observe the
 153 .B Linux FSSTND
 154 the keyword
 155 .B FSSTND
 156 can be used in place of an actual directory.
 157
 158 Unfortunately, it is necessary to specify
 159 .B all
 160 system man tree paths, including alternate operating system paths such as
 161 .I /usr/man/sun
 162 and any
 163 .B NLS locale
 164 paths such as
 165 .IR /usr/man/de_DE.88591 .
 166
 167 As the information is parsed line by line in the order written, it is
 168 necessary for any manpath that is a sub-hierarchy of another hierarchy to be
 169 listed first, otherwise an incorrect match will be made.
 170 An example is that
 171 .I /usr/man/de_DE.88591
 172 must come before
 173 .IR /usr/man .
 174 .TP
 175 .BI DEFINE \ key\ value
 176 Lines of this form define miscellaneous configuration variables; see the
 177 default configuration file for those variables used by the manual pager
 178 utilities.
 179 They include default paths to various programs (such as
 180 .I grep
 181 and
 182 .IR tbl ),
 183 and default sets of arguments to those programs.
 184 .TP
 185 \fBSECTION\fR \fIsection\fR .\|.\|.
 186 .RS
 187 Lines of this form define the order in which manual sections should be
 188 searched.
 189 If there are no
 190 .B SECTION
 191 directives in the configuration file, the default is:
 192 .PP
 193 .RS
 194 .nf
 195 .if !'po4a'hide' SECTION 1 n l 8 3 0 2 5 4 9 6 7
 196 .fi
 197 .RE
 198 .PP
 199 If multiple
 200 .B SECTION
 201 directives are given, their section lists will be concatenated.
 202 .PP
 203 If a particular extension is not in this list (say, 1mh) it will be
 204 displayed with the rest of the section it belongs to.
 205 The effect of this is that you only need to explicitly list extensions if
 206 you want to force a particular order.
 207 Sections with extensions should usually be adjacent to their main section
 208 (e.g. "1 1mh 8 ...").
 209 .PP
 210 .B SECTIONS
 211 is accepted as an alternative name for this directive.
 212 .RE
 213 .TP
 214 .BI MINCATWIDTH \ width
 215 If the terminal width is less than
 216 .IR width ,
 217 cat pages will not be created (if missing) or displayed.
 218 The default is 80.
 219 .TP
 220 .BI MAXCATWIDTH \ width
 221 If the terminal width is greater than
 222 .IR width ,
 223 cat pages will not be created (if missing) or displayed.
 224 The default is 80.
 225 .TP
 226 .BI CATWIDTH \ width
 227 If
 228 .I width
 229 is non-zero, cat pages will always be formatted for a terminal of the given
 230 width, regardless of the width of the terminal actually being used.
 231 This should generally be within the range set by
 232 .B MINCATWIDTH
 233 and
 234 .BR MAXCATWIDTH .
 235 .TP
 236 .if !'po4a'hide' .B NOCACHE
 237 This flag prevents
 238 .BR %man% (1)
 239 from creating cat pages automatically.
 240 .SH BUGS
 241 Unless the rules above are followed and observed precisely, the manual pager
 242 utilities will not function as desired.
 243 The rules are overly complicated.
 244 .PP
 245 .if !'po4a'hide' https://gitlab.com/cjwatson/man-db/-/issues
 246 .br
 247 .if !'po4a'hide' https://savannah.nongnu.org/bugs/?group=man-db