usr.bin/man/man.conf.5

   1 .\"     $NetBSD: man.conf.5,v 1.19 2006/04/13 21:15:50 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 April 10, 2006
  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 "_version"
  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 Any occurrences of the string
 102 .Dq %s
 103 in the shell command line 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 .It _default
 114 contains the system-wide default man path used to search for man pages.
 115 .It _subdir
 116 contains the list (in search order) of section subdirectories which will
 117 be searched in any man path directory named with a trailing slash
 118 .Pq Dq /
 119 character.
 120 This list is also used, even if there is no trailing slash character,
 121 when a path is specified to the
 122 .Xr man 1
 123 utility by the user, by the
 124 .Ev MANPATH
 125 environment variable, or by the
 126 .Fl M
 127 and
 128 .Fl m
 129 options.
 130 .It _suffix
 131 identifies the set of suffixes used for formatted man pages
 132 (the
 133 .Dq \.0
 134 suffix is normally used here).
 135 Formatted man pages can be directly displayed to the user.
 136 Each suffix may contain the normal shell globbing characters (NOT
 137 including curly braces
 138 .Pq Dq {} ) .
 139 .It _version
 140 contains the version of the configuration file.
 141 .It _whatdb
 142 defines the full pathname (not just a directory path) for a database to
 143 be used
 144 by the
 145 .Xr apropos 1
 146 and
 147 .Xr whatis 1
 148 commands.
 149 The pathname may contain the normal shell globbing characters,
 150 including curly braces
 151 .Pq Dq {} ;
 152 to escape a shell globbing character,
 153 precede it with a backslash
 154 .Pq Dq \e .
 155 .El
 156 .Pp
 157 Section configuration lines in
 158 .Nm
 159 consist of a section keyword naming the section and a configuration
 160 string that defines the directory or subdirectory path that the section's
 161 manual pages are located in.
 162 The path may contain the normal shell globbing characters,
 163 including curly braces
 164 .Pq Dq {} ;
 165 to escape a shell globbing character,
 166 precede it with a backslash
 167 .Pq Dq \e .
 168 Section keywords must not start with the
 169 .Dq _
 170 character.
 171 .Pp
 172 A section path may contain either a list of absolute directories or
 173 a list of or relative directories (but not both).
 174 Relative directory paths are treated as a list of subdirectories that
 175 are appended to the current man path directory being searched.
 176 Section configuration lines with absolute directory paths (starting with
 177 .Dq / )
 178 completely replace the current man search path directory with their
 179 content.
 180 .Pp
 181 Section configuration lines with absolute directory paths ending
 182 with a trailing slash character are expected to contain subdirectories
 183 of manual pages, (see the keyword
 184 .Dq _subdir
 185 above).
 186 The
 187 .Dq _subdir
 188 subdirectory list is not applied to absolute section directories
 189 if there is no trailing slash.
 190 .Pp
 191 In addition to the above rules, the
 192 .Xr man 1
 193 command also always checks in each directory that it searches for
 194 a subdirectory with the same name as the current machine type.
 195 If the machine-specific directory is found, it is also searched.
 196 This allows the manual to contain machine-specific man pages.
 197 Note that the machine subdirectory does not need to be specified
 198 in the
 199 .Nm
 200 file.
 201 .Pp
 202 Multiple specifications for all types of
 203 .Nm
 204 configuration lines are
 205 cumulative and the entries are used in the order listed in the file;
 206 multiple entries may be listed per line, as well.
 207 .Sh FILES
 208 .Bl -tag -width /etc/man.conf -compact
 209 .It Pa /etc/man.conf
 210 Standard manual configuration file.
 211 .El
 212 .Sh EXAMPLES
 213 Given the following
 214 .Nm
 215 file:
 216 .Bd -literal -offset indent
 217 _version        BSD.2
 218 _subdir         cat[123]
 219 _suffix         .0
 220 _build          .[1-9]  nroff -man %s
 221 _build          .tbl    tbl %s | nroff -man
 222 _default        /usr/share/man/
 223 sect3           /usr/share/man/{old/,}cat3
 224 .Ed
 225 .Pp
 226 By default, the command
 227 .Dq Li man mktemp
 228 will search for
 229 .Dq mktemp.\*[Lt]any_digit\*[Gt]
 230 and
 231 .Dq mktemp.tbl
 232 in the directories
 233 .Dq Pa /usr/share/man/cat1 ,
 234 .Dq Pa /usr/share/man/cat2 ,
 235 and
 236 .Dq Pa /usr/share/man/cat3 .
 237 If on a machine of type
 238 .Dq vax ,
 239 the subdirectory
 240 .Dq vax
 241 in each
 242 directory would be searched as well, before the directory was
 243 searched.
 244 .Pp
 245 If
 246 .Dq mktemp.tbl
 247 was found first, the command
 248 .Dq Li tbl \*[Lt]manual page\*[Gt] | nroff -man
 249 would be run to build a man page for display to the user.
 250 .Pp
 251 The command
 252 .Dq Li man sect3 mktemp
 253 would search the directories
 254 .Dq Pa /usr/share/man/old/cat3
 255 and
 256 .Dq Pa /usr/share/man/cat3 ,
 257 in that order, for
 258 the mktemp manual page.
 259 If a subdirectory with the same name as the current machine type
 260 existed in any of them, it would be searched as well, before each
 261 of them were searched.
 262 .Sh SEE ALSO
 263 .Xr apropos 1 ,
 264 .Xr machine 1 ,
 265 .Xr man 1 ,
 266 .Xr whatis 1 ,
 267 .Xr whereis 1 ,
 268 .Xr fnmatch 3 ,
 269 .Xr glob 3 ,
 270 .Xr catman 8 ,
 271 .Xr makewhatis 8