usr.bin/man/man.conf.5

   1 .\"     $NetBSD: man.conf.5,v 1.24 2013/06/28 10:13:18 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1989, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)man.conf.5  8.5 (Berkeley) 1/2/94
  31 .\"
  32 .Dd October 5, 2013
  33 .Dt MAN.CONF 5
  34 .Os
  35 .Sh NAME
  36 .Nm man.conf
  37 .Nd configuration file for manual pages
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 file contains the default configuration used by
  42 .Xr man 1 ,
  43 .Xr apropos 1 ,
  44 .Xr whatis 1 ,
  45 .Xr catman 8 ,
  46 and
  47 .Xr makewhatis 8
  48 to find manual pages and information about manual pages (e.g. the
  49 whatis database).
  50 .Pp
  51 Manual pages are located by searching an ordered set of directories
  52 called the
  53 .Dq man path
  54 for a file that matches the name of the requested page.
  55 Each directory in the search path usually has a set of subdirectories
  56 in it (though this is not required).
  57 When subdirectories are used, there are normally two subdirectories
  58 for each section of the manual.
  59 One subdirectory contains formatted copies of that section's manual
  60 pages that can be directly displayed to a terminal, while the other
  61 section subdirectory contains unformatted copies of the pages (see
  62 .Xr nroff 1
  63 and
  64 .Xr mdoc 7 ) .
  65 Formatted manual pages are normally named with a trailing
  66 .Dq \.0
  67 suffix.
  68 .Pp
  69 The
  70 .Nm
  71 file contains comment and configuration lines.
  72 Comment lines start with the
  73 .Dq #
  74 character.
  75 Blank lines are also treated as comment lines.
  76 Configuration lines consist of a configuration keyword followed by a
  77 configuration string.
  78 There are two types of configuration keywords: control keywords and
  79 section keywords.
  80 Control keywords must start with the
  81 .Dq _
  82 character.
  83 The following control keywords are currently defined:
  84 .Bl -tag -width XXmachineX
  85 .It _build
  86 Identifies the set of suffixes used for manual pages that must be
  87 formatted for display and the command that should be used to format
  88 them.
  89 Manual file names, regardless of their format, are expected to end in a
  90 .Dq \.*
  91 pattern, i.e. a
  92 .Dq \&\.
  93 followed by some suffix.
  94 The first field of a _build line contains a man page suffix specification.
  95 The suffix specification may contain the normal shell globbing characters
  96 (NOT including curly braces
  97 .Pq Dq {} ) .
  98 The rest of the _build line is a shell command line whose standard
  99 output is a formatted manual page that can be directly displayed to
 100 the user.
 101 There should be exactly one occurrence of the string
 102 .Dq %s
 103 in the shell command line, and it will
 104 be replaced by the name of the file which is being formatted.
 105 .It _crunch
 106 Used by
 107 .Xr catman 8
 108 to determine how to crunch formatted pages
 109 which originally were compressed man pages: The first field lists a suffix
 110 which indicates what kind of compression were used to compress the man page.
 111 The rest of the line must be a shell command line, used to compress the
 112 formatted pages.
 113 There should be exactly one occurrence of the string
 114 .Dq %s
 115 in the shell command line, and it will
 116 be replaced by the name of the output file.
 117 .It _default
 118 Contains the system-wide default man path used to search for man pages.
 119 .It _subdir
 120 Contains the list (in search order) of section subdirectories which will
 121 be searched in any man path directory named with a trailing slash
 122 .Pq Dq /
 123 character.
 124 This list is also used, even if there is no trailing slash character,
 125 when a path is specified to the
 126 .Xr man 1
 127 utility by the user, by the
 128 .Ev MANPATH
 129 environment variable, or by the
 130 .Fl M
 131 and
 132 .Fl m
 133 options.
 134 .It _suffix
 135 identifies the set of suffixes used for formatted man pages
 136 (the
 137 .Dq \.0
 138 suffix is normally used here).
 139 Formatted man pages can be directly displayed to the user.
 140 Each suffix may contain the normal shell globbing characters (NOT
 141 including curly braces
 142 .Pq Dq {} ) .
 143 .It _version
 144 Contains the version of the configuration file.
 145 .It _whatdb
 146 Defines the full pathname (not just a directory path) for a database to
 147 be used
 148 by the
 149 .Xr apropos 1
 150 and
 151 .Xr whatis 1
 152 commands.
 153 The pathname may contain the normal shell globbing characters,
 154 including curly braces
 155 .Pq Dq {} ;
 156 to escape a shell globbing character,
 157 precede it with a backslash
 158 .Pq Dq \e .
 159 .It _ Ns Aq machine
 160 Defines additional paths to be searched for the particular
 161 .Dv machine
 162 whose literal value is taken from
 163 .Xr uname 1
 164 .Fl m .
 165 For example on an
 166 .Dv amd64 ,
 167 .Dv _amd64
 168 is used.
 169 .El
 170 .Pp
 171 Section configuration lines in
 172 .Nm
 173 consist of a section keyword naming the section and a configuration
 174 string that defines the directory or subdirectory path that the section's
 175 manual pages are located in.
 176 The path may contain the normal shell globbing characters,
 177 including curly braces
 178 .Pq Dq {} ;
 179 to escape a shell globbing character,
 180 precede it with a backslash
 181 .Pq Dq \e .
 182 Section keywords must not start with the
 183 .Dq _
 184 character.
 185 .Pp
 186 A section path may contain either a list of absolute directories or
 187 a list of or relative directories (but not both).
 188 Relative directory paths are treated as a list of subdirectories that
 189 are appended to the current man path directory being searched.
 190 Section configuration lines with absolute directory paths (starting with
 191 .Dq / )
 192 completely replace the current man search path directory with their
 193 content.
 194 .Pp
 195 Section configuration lines with absolute directory paths ending
 196 with a trailing slash character are expected to contain subdirectories
 197 of manual pages, (see the keyword
 198 .Dq _subdir
 199 above).
 200 The
 201 .Dq _subdir
 202 subdirectory list is not applied to absolute section directories
 203 if there is no trailing slash.
 204 .Pp
 205 In addition to the above rules, the
 206 .Xr man 1
 207 command also always checks in each directory that it searches for
 208 a subdirectory with the same name as the current machine type.
 209 If the machine-specific directory is found, it is also searched.
 210 This allows the manual to contain machine-specific man pages.
 211 Note that the machine subdirectory does not need to be specified
 212 in the
 213 .Nm
 214 file.
 215 .Pp
 216 Multiple specifications for all types of
 217 .Nm
 218 configuration lines are
 219 cumulative and the entries are used in the order listed in the file;
 220 multiple entries may be listed per line, as well.
 221 .Sh FILES
 222 .Bl -tag -width /etc/man.conf -compact
 223 .It Pa /etc/man.conf
 224 Standard manual configuration file.
 225 .El
 226 .Sh EXAMPLES
 227 Given the following
 228 .Nm
 229 file:
 230 .Bd -literal -offset indent
 231 _version        BSD.2
 232 _subdir         cat[123]
 233 _suffix         .0
 234 _build          .[1-9]  nroff -man %s
 235 _build          .tbl    tbl %s | nroff -man
 236 _i386           x86
 237 _default        /usr/share/man/
 238 sect3           /usr/share/man/{old/,}cat3
 239 .Ed
 240 .Pp
 241 By default, the command
 242 .Dq Li man mktemp
 243 will search for
 244 .Dq mktemp. Ns Aq any_digit
 245 and
 246 .Dq mktemp.tbl
 247 in the directories
 248 .Dq Pa /usr/share/man/cat1 ,
 249 .Dq Pa /usr/share/man/cat2 ,
 250 and
 251 .Dq Pa /usr/share/man/cat3 .
 252 If on a machine of type
 253 .Dq vax ,
 254 the subdirectory
 255 .Dq vax
 256 in each
 257 directory would be searched as well, before the directory was
 258 searched.
 259 .Pp
 260 If
 261 .Dq mktemp.tbl
 262 was found first, the command
 263 .Dq Li tbl Ao manual page Ac | nroff -man
 264 would be run to build a man page for display to the user.
 265 .Pp
 266 The command
 267 .Dq Li man sect3 mktemp
 268 would search the directories
 269 .Dq Pa /usr/share/man/old/cat3
 270 and
 271 .Dq Pa /usr/share/man/cat3 ,
 272 in that order, for
 273 the mktemp manual page.
 274 If a subdirectory with the same name as the current machine type
 275 existed in any of them, it would be searched as well, before each
 276 of them were searched.
 277 .Sh SEE ALSO
 278 .Xr apropos 1 ,
 279 .Xr machine 1 ,
 280 .Xr man 1 ,
 281 .Xr whatis 1 ,
 282 .Xr whereis 1 ,
 283 .Xr fnmatch 3 ,
 284 .Xr glob 3 ,
 285 .Xr catman 8 ,
 286 .Xr makewhatis 8