Annotation of src/usr.bin/man/man.conf.5, Revision 1.13
1.13 ! jmc 1: .\" $OpenBSD: man.conf.5,v 1.12 2007/05/31 19:20:13 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: .\"
1.13 ! jmc 32: .Dd $Mdocdate: May 31 2007 $
1.1 deraadt 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
1.13 ! jmc 50: .Xr mandoc 1 )
1.11 jmc 51: and named with a trailing
52: .Sq .0 .
1.1 deraadt 53: .Pp
54: The
55: .Nm man.conf
56: file contains two types of lines.
57: .Pp
1.11 jmc 58: The first type of line is a
59: .Dq section
60: line, which contains a section name followed by one or more directory paths.
1.1 deraadt 61: The directory paths may contain the normal shell globbing characters,
1.11 jmc 62: including curly braces
63: .Pq Sq {} ;
64: to escape a shell globbing character, precede it with a backslash
65: .Pq Sq \e .
1.1 deraadt 66: Lines in this format specify that manual pages for the section
67: may be found in the following directories.
68: .Pp
1.11 jmc 69: Directories named with a trailing slash character
70: .Pq Sq /
71: are expected to contain subdirectories of manual pages, (see the keyword
72: .Dq _subdir
1.1 deraadt 73: below) instead of manual pages.
74: These subdirectories are searched instead of the directory.
75: .Pp
76: Before searching any directory for a manual page, the
77: .Xr man 1
78: command always searches the subdirectory with the same name
79: as the current machine type, if it exists.
80: No specification of these subdirectories is necessary in the
81: .Nm man.conf
82: file.
83: .Pp
84: Section names are unrestricted except for the reserved words specified
85: below; in general, you should avoid anything with a leading underscore
1.11 jmc 86: .Pq Sq _
87: to avoid future incompatibilities.
1.1 deraadt 88: .Pp
1.11 jmc 89: The section named
90: .Dq _default
91: is the list of directories that will
1.1 deraadt 92: be searched if no section is specified by the user.
93: .Pp
1.11 jmc 94: The second type of line is preceded with a
95: .Dq keyword .
1.1 deraadt 96: The possible keywords and their meanings are as follows:
97: .Bl -tag -width "_version"
98: .It _build
1.11 jmc 99: Man file names, regardless of their format, are expected to end in a
100: .Sq .*
101: pattern, i.e. a
102: .Sq .\&
103: followed by some suffix.
1.1 deraadt 104: The first field of a _build line lists a suffix which indicates
1.6 alex 105: files which need to be reformatted or manipulated in some way before
1.1 deraadt 106: being displayed to the user.
107: The suffix may contain the normal shell globbing characters (NOT
1.11 jmc 108: including curly braces
109: .Pq Sq {} ) .
1.1 deraadt 110: The rest of the line must be a shell command line, the standard
111: output of which is the manual page in a format which may be directly
112: displayed to the user.
1.11 jmc 113: Any occurrences of the string
114: .Sq %s
115: in the shell command line will
1.1 deraadt 116: be replaced by the name of the file which is being reformatted.
117: .It _subdir
1.11 jmc 118: The list
119: .Pq in search order
120: of subdirectories which will be searched in
121: any directory named with a trailing slash
122: .Pq Sq /
123: character.
1.1 deraadt 124: This list is also used when a path is specified to the
125: .Xr man 1
126: utility by the user, using the
127: .Ev MANPATH
128: environment variable or the
129: .Fl M
130: and
131: .Fl m
132: options.
133: .It _suffix
1.11 jmc 134: Man file names, regardless of their format, are expected to end in a
135: .Sq .*
136: pattern, i.e. a
137: .Sq .\&
138: followed by some suffix.
1.1 deraadt 139: Each field of a _suffix line is a suffix which indicates
140: files which do not need to be reformatted or manipulated
141: in any way, but which may be directly displayed to the user.
142: Each suffix may contain the normal shell globbing characters (NOT
1.11 jmc 143: including curly braces
144: .Pq Sq {} ) .
1.1 deraadt 145: .It _version
146: The version of the configuration file.
147: .It _whatdb
1.11 jmc 148: The full pathname
149: .Pq not just a directory path
150: for a database to be used by the
1.1 deraadt 151: .Xr apropos 1
152: and
153: .Xr whatis 1
154: commands.
155: .El
156: .Pp
157: Multiple specifications for all types of lines are cumulative and the
158: entries are used in the order listed in the file; multiple entries may
159: be listed per line, as well.
160: .Pp
1.11 jmc 161: Empty lines or lines whose first non-whitespace character is a hash mark
162: .Pq Sq #
163: are ignored.
1.10 jmc 164: .Sh FILES
165: .Bl -tag -width /etc/man.conf -compact
166: .It Pa /etc/man.conf
167: standard manual directory search path
168: .El
1.1 deraadt 169: .Sh EXAMPLES
170: Given the following
171: .Nm man.conf
172: file:
173: .Bd -literal -offset indent
174: _version BSD.2
1.13 ! jmc 175: _subdir cat1 cat3 cat2
1.1 deraadt 176: _suffix .0
1.13 ! jmc 177: _build .[1-9] /usr/bin/mandoc %s
! 178: _build .tbl /usr/bin/mandoc %s
1.1 deraadt 179: _default /usr/share/man/
180: sect3 /usr/share/man/{old/,}cat3
181: .Ed
182: .Pp
183: By default, the command
184: .Dq Li man mktemp
185: will search for
1.11 jmc 186: .Dq mktemp.\*(Ltany_digit\*(Gt
187: and
188: .Dq mktemp.tbl
1.1 deraadt 189: in the directories
1.11 jmc 190: .Pa /usr/share/man/cat1 ,
1.13 ! jmc 191: .Pa /usr/share/man/cat3 ,
! 192: and
1.11 jmc 193: .Pa /usr/share/man/cat2 ,
1.13 ! jmc 194: in that order.
1.11 jmc 195: If on a machine of type
196: .Dq vax ,
197: the subdirectory
198: .Dq vax
1.13 ! jmc 199: in each directory would be searched as well,
! 200: before the rest of the directory was searched.
1.1 deraadt 201: .Pp
1.11 jmc 202: If
203: .Dq mktemp.tbl
204: was found first, the command
1.13 ! jmc 205: .Dq /usr/bin/mandoc mktemp.tbl
1.1 deraadt 206: would be run to build a man page for display to the user.
207: .Pp
208: The command
209: .Dq Li man sect3 mktemp
210: would search the directories
1.11 jmc 211: .Pa /usr/share/man/old/cat3
1.1 deraadt 212: and
1.11 jmc 213: .Pa /usr/share/man/cat3 ,
1.13 ! jmc 214: in that order, for the mktemp manual page.
1.1 deraadt 215: If a subdirectory with the same name as the current machine type
216: existed in any of them, it would be searched as well, before each
217: of them were searched.
218: .Sh SEE ALSO
219: .Xr apropos 1 ,
220: .Xr machine 1 ,
221: .Xr man 1 ,
222: .Xr whatis 1 ,
223: .Xr whereis 1 ,
224: .Xr fnmatch 3 ,
225: .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