| blob | 0a2827543c9be88e5e7a3a4e7acb7f794cd7a042 |
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