Annotation of src/usr.bin/man/man.conf.5, Revision 1.9
1.9 ! millert 1: .\" $OpenBSD: man.conf.5,v 1.8 2003/01/21 19:59:09 jmc Exp $
1.2 deraadt 2: .\"
1.1 deraadt 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.
1.9 ! millert 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 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 January 2, 1994
33: .Dt MAN.CONF 5
34: .Os
35: .Sh NAME
36: .Nm man.conf
37: .Nd configuration file for
38: .Xr man 1
39: .Sh DESCRIPTION
40: The
41: .Xr man 1 ,
42: .Xr apropos 1 ,
43: and
44: .Xr whatis 1
45: commands
46: search for manual pages or their database files as specified by the
47: .Nm man.conf
48: file.
49: Manual pages are normally expected to be preformatted (see
50: .Xr nroff 1 )
51: and named with a trailing ``.0''.
52: .Pp
53: The
54: .Nm man.conf
55: file contains two types of lines.
56: .Pp
57: The first type of line is a ``section'' line, which contains a
58: section name followed by one or more directory paths.
59: The directory paths may contain the normal shell globbing characters,
60: including curly braces (``{}''); to escape a shell globbing character,
61: precede it with a backslash (``\e'').
62: Lines in this format specify that manual pages for the section
63: may be found in the following directories.
64: .Pp
65: Directories named with a trailing slash character (``/'') are expected
66: to contain subdirectories of manual pages, (see the keyword ``_subdir''
67: below) instead of manual pages.
68: These subdirectories are searched instead of the directory.
69: .Pp
70: Before searching any directory for a manual page, the
71: .Xr man 1
72: command always searches the subdirectory with the same name
73: as the current machine type, if it exists.
74: No specification of these subdirectories is necessary in the
75: .Nm man.conf
76: file.
77: .Pp
78: Section names are unrestricted except for the reserved words specified
79: below; in general, you should avoid anything with a leading underscore
80: (``_'') to avoid future incompatibilities.
81: .Pp
82: The section named ``_default'' is the list of directories that will
83: be searched if no section is specified by the user.
84: .Pp
85: The second type of line is preceded with a ``keyword''.
86: The possible keywords and their meanings are as follows:
87: .Bl -tag -width "_version"
88: .It _build
89: Man file names, regardless of their format, are expected to end in
1.7 aaron 90: a ``.*'' pattern, i.e., a ``.'' followed by some suffix.
1.1 deraadt 91: The first field of a _build line lists a suffix which indicates
1.6 alex 92: files which need to be reformatted or manipulated in some way before
1.1 deraadt 93: being displayed to the user.
94: The suffix may contain the normal shell globbing characters (NOT
95: including curly braces (``{}'')).
96: The rest of the line must be a shell command line, the standard
97: output of which is the manual page in a format which may be directly
98: displayed to the user.
99: Any occurrences of the string ``%s'' in the shell command line will
100: be replaced by the name of the file which is being reformatted.
101: .It _subdir
102: The list (in search order) of subdirectories which will be searched in
103: any directory named with a trailing slash (``/'') character.
104: This list is also used when a path is specified to the
105: .Xr man 1
106: utility by the user, using the
107: .Ev MANPATH
108: environment variable or the
109: .Fl M
110: and
111: .Fl m
112: options.
113: .It _suffix
1.3 aaron 114: Man file names, regardless of their format, are expected to end in
1.1 deraadt 115: a ``.*'' pattern, i.e. a ``.'' followed by some suffix.
116: Each field of a _suffix line is a suffix which indicates
117: files which do not need to be reformatted or manipulated
118: in any way, but which may be directly displayed to the user.
119: Each suffix may contain the normal shell globbing characters (NOT
120: including curly braces (``{}'')).
121: .It _version
122: The version of the configuration file.
123: .It _whatdb
124: The full pathname (not just a directory path) for a database to be used
125: by the
126: .Xr apropos 1
127: and
128: .Xr whatis 1
129: commands.
130: .El
131: .Pp
132: Multiple specifications for all types of lines are cumulative and the
133: entries are used in the order listed in the file; multiple entries may
134: be listed per line, as well.
135: .Pp
136: Empty lines or lines whose first non-whitespace character is a hash
137: mark (``#'') are ignored.
138: .Sh EXAMPLES
139: Given the following
140: .Nm man.conf
141: file:
142: .Bd -literal -offset indent
143: _version BSD.2
144: _subdir cat[123]
145: _suffix .0
146: _build .[1-9] nroff -man %s
147: _build .tbl tbl %s | nroff -man
148: _default /usr/share/man/
149: sect3 /usr/share/man/{old/,}cat3
150: .Ed
151: .Pp
152: By default, the command
153: .Dq Li man mktemp
154: will search for
155: ``mktemp.<any_digit>'' and ``mktemp.tbl''
156: in the directories
1.5 aaron 157: .Dq Pa /usr/share/man/cat1 ,
158: .Dq Pa /usr/share/man/cat2 ,
1.1 deraadt 159: and
160: .Dq Pa /usr/share/man/cat3 .
161: If on a machine of type ``vax'', the subdirectory ``vax'' in each
162: directory would be searched as well, before the directory was
163: searched.
164: .Pp
165: If ``mktemp.tbl'' was found first, the command
1.8 jmc 166: .Dq Li tbl <manual page> \&| nroff -man
1.1 deraadt 167: would be run to build a man page for display to the user.
168: .Pp
169: The command
170: .Dq Li man sect3 mktemp
171: would search the directories
172: .Dq Pa /usr/share/man/old/cat3
173: and
174: .Dq Pa /usr/share/man/cat3 ,
175: in that order, for
1.3 aaron 176: the
177: .Xr mktemp 1
178: manual page.
1.1 deraadt 179: If a subdirectory with the same name as the current machine type
180: existed in any of them, it would be searched as well, before each
181: of them were searched.
182: .Sh FILES
183: .Bl -tag -width /etc/man.conf -compact
184: .It Pa /etc/man.conf
1.3 aaron 185: standard manual directory search path
1.1 deraadt 186: .El
187: .Sh SEE ALSO
188: .Xr apropos 1 ,
189: .Xr machine 1 ,
190: .Xr man 1 ,
191: .Xr whatis 1 ,
192: .Xr whereis 1 ,
193: .Xr fnmatch 3 ,
194: .Xr glob 3
![[BACK]](/icons/back.gif){kind=icon}
Return to man.conf.5 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / man