Annotation of src/usr.bin/man/man.conf.5, Revision 1.8
1.8 ! jmc 1: .\" $OpenBSD: man.conf.5,v 1.7 2000/03/14 21:31:35 aaron 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.
14: .\" 3. All advertising materials mentioning features or use of this software
15: .\" must display the following acknowledgement:
16: .\" This product includes software developed by the University of
17: .\" California, Berkeley and its contributors.
18: .\" 4. Neither the name of the University nor the names of its contributors
19: .\" may be used to endorse or promote products derived from this software
20: .\" without specific prior written permission.
21: .\"
22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32: .\" SUCH DAMAGE.
33: .\"
34: .\" @(#)man.conf.5 8.5 (Berkeley) 1/2/94
35: .\"
36: .Dd January 2, 1994
37: .Dt MAN.CONF 5
38: .Os
39: .Sh NAME
40: .Nm man.conf
41: .Nd configuration file for
42: .Xr man 1
43: .Sh DESCRIPTION
44: The
45: .Xr man 1 ,
46: .Xr apropos 1 ,
47: and
48: .Xr whatis 1
49: commands
50: search for manual pages or their database files as specified by the
51: .Nm man.conf
52: file.
53: Manual pages are normally expected to be preformatted (see
54: .Xr nroff 1 )
55: and named with a trailing ``.0''.
56: .Pp
57: The
58: .Nm man.conf
59: file contains two types of lines.
60: .Pp
61: The first type of line is a ``section'' line, which contains a
62: section name followed by one or more directory paths.
63: The directory paths may contain the normal shell globbing characters,
64: including curly braces (``{}''); to escape a shell globbing character,
65: precede it with a backslash (``\e'').
66: Lines in this format specify that manual pages for the section
67: may be found in the following directories.
68: .Pp
69: Directories named with a trailing slash character (``/'') are expected
70: to contain subdirectories of manual pages, (see the keyword ``_subdir''
71: below) instead of manual pages.
72: These subdirectories are searched instead of the directory.
73: .Pp
74: Before searching any directory for a manual page, the
75: .Xr man 1
76: command always searches the subdirectory with the same name
77: as the current machine type, if it exists.
78: No specification of these subdirectories is necessary in the
79: .Nm man.conf
80: file.
81: .Pp
82: Section names are unrestricted except for the reserved words specified
83: below; in general, you should avoid anything with a leading underscore
84: (``_'') to avoid future incompatibilities.
85: .Pp
86: The section named ``_default'' is the list of directories that will
87: be searched if no section is specified by the user.
88: .Pp
89: The second type of line is preceded with a ``keyword''.
90: The possible keywords and their meanings are as follows:
91: .Bl -tag -width "_version"
92: .It _build
93: Man file names, regardless of their format, are expected to end in
1.7 aaron 94: a ``.*'' pattern, i.e., a ``.'' followed by some suffix.
1.1 deraadt 95: The first field of a _build line lists a suffix which indicates
1.6 alex 96: files which need to be reformatted or manipulated in some way before
1.1 deraadt 97: being displayed to the user.
98: The suffix may contain the normal shell globbing characters (NOT
99: including curly braces (``{}'')).
100: The rest of the line must be a shell command line, the standard
101: output of which is the manual page in a format which may be directly
102: displayed to the user.
103: Any occurrences of the string ``%s'' in the shell command line will
104: be replaced by the name of the file which is being reformatted.
105: .It _subdir
106: The list (in search order) of subdirectories which will be searched in
107: any directory named with a trailing slash (``/'') character.
108: This list is also used when a path is specified to the
109: .Xr man 1
110: utility by the user, using the
111: .Ev MANPATH
112: environment variable or the
113: .Fl M
114: and
115: .Fl m
116: options.
117: .It _suffix
1.3 aaron 118: Man file names, regardless of their format, are expected to end in
1.1 deraadt 119: a ``.*'' pattern, i.e. a ``.'' followed by some suffix.
120: Each field of a _suffix line is a suffix which indicates
121: files which do not need to be reformatted or manipulated
122: in any way, but which may be directly displayed to the user.
123: Each suffix may contain the normal shell globbing characters (NOT
124: including curly braces (``{}'')).
125: .It _version
126: The version of the configuration file.
127: .It _whatdb
128: The full pathname (not just a directory path) for a database to be used
129: by the
130: .Xr apropos 1
131: and
132: .Xr whatis 1
133: commands.
134: .El
135: .Pp
136: Multiple specifications for all types of lines are cumulative and the
137: entries are used in the order listed in the file; multiple entries may
138: be listed per line, as well.
139: .Pp
140: Empty lines or lines whose first non-whitespace character is a hash
141: mark (``#'') are ignored.
142: .Sh EXAMPLES
143: Given the following
144: .Nm man.conf
145: file:
146: .Bd -literal -offset indent
147: _version BSD.2
148: _subdir cat[123]
149: _suffix .0
150: _build .[1-9] nroff -man %s
151: _build .tbl tbl %s | nroff -man
152: _default /usr/share/man/
153: sect3 /usr/share/man/{old/,}cat3
154: .Ed
155: .Pp
156: By default, the command
157: .Dq Li man mktemp
158: will search for
159: ``mktemp.<any_digit>'' and ``mktemp.tbl''
160: in the directories
1.5 aaron 161: .Dq Pa /usr/share/man/cat1 ,
162: .Dq Pa /usr/share/man/cat2 ,
1.1 deraadt 163: and
164: .Dq Pa /usr/share/man/cat3 .
165: If on a machine of type ``vax'', the subdirectory ``vax'' in each
166: directory would be searched as well, before the directory was
167: searched.
168: .Pp
169: If ``mktemp.tbl'' was found first, the command
1.8 ! jmc 170: .Dq Li tbl <manual page> \&| nroff -man
1.1 deraadt 171: would be run to build a man page for display to the user.
172: .Pp
173: The command
174: .Dq Li man sect3 mktemp
175: would search the directories
176: .Dq Pa /usr/share/man/old/cat3
177: and
178: .Dq Pa /usr/share/man/cat3 ,
179: in that order, for
1.3 aaron 180: the
181: .Xr mktemp 1
182: manual page.
1.1 deraadt 183: If a subdirectory with the same name as the current machine type
184: existed in any of them, it would be searched as well, before each
185: of them were searched.
186: .Sh FILES
187: .Bl -tag -width /etc/man.conf -compact
188: .It Pa /etc/man.conf
1.3 aaron 189: standard manual directory search path
1.1 deraadt 190: .El
191: .Sh SEE ALSO
192: .Xr apropos 1 ,
193: .Xr machine 1 ,
194: .Xr man 1 ,
195: .Xr whatis 1 ,
196: .Xr whereis 1 ,
197: .Xr fnmatch 3 ,
198: .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