1.\" $NetBSD: man.conf.5,v 1.16 2003/08/07 11:15:10 agc 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 June 26, 2001 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 40The 41.Xr man 1 , 42.Xr apropos 1 , 43.Xr whatis 1 44and 45.Xr makewhatis 8 46commands 47search for manual pages or their database files as specified by the 48.Nm 49file. 50Manual pages are normally expected to be preformatted (see 51.Xr nroff 1 ) 52and named with a trailing 53.Dq \.0 . 54.Pp 55The 56.Nm 57file contains two types of lines. 58.Pp 59The first type of line is a 60.Dq section 61line, which contains a 62section name followed by one or more directory paths. 63The directory paths may contain the normal shell globbing characters, 64including curly braces 65.Pq Dq {} ; 66to escape a shell globbing character, 67precede it with a backslash 68.Pq Dq \e . 69Lines in this format specify that manual pages for the section 70may be found in the following directories. 71.Pp 72Section lines may contain either absolute directory paths or relative 73directory paths (but not both). 74Relative directory paths are treated 75as a list of subdirectories to append to the current directory search 76path. 77Section lines with absolute directory paths (starting with 78.Dq / ) 79completely replace the current directory search path with their 80content. 81Absolute directory paths named with a trailing slash 82character are expected to contain subdirectories of manual pages, (see 83the keyword 84.Dq _subdir 85below) instead of man pages. 86These 87subdirectories are searched instead of the directory. 88.Pp 89Before searching any directory for a manual page, the 90.Xr man 1 91command always searches the subdirectory with the same name 92as the current machine type, if it exists. 93No specification of these subdirectories is necessary in the 94.Nm 95file. 96.Pp 97Section names are unrestricted except for the reserved words specified 98below; in general, you should avoid anything with a leading underscore 99.Pq Dq _ 100to avoid future incompatibilities. 101.Pp 102The section named 103.Dq _default 104is the list of directories that will 105be searched if no section is specified by the user. 106.Pp 107The second type of line is preceded with a 108.Dq keyword . 109The possible keywords and their meanings are as follows: 110.Pp 111.Bl -tag -width "_version" 112.It _build 113Man file names, regardless of their format, are expected to end in 114a 115.Dq \.* 116pattern, i.e. a 117.Dq \&\. 118followed by some suffix. 119The first field of a _build line lists a suffix which indicates 120files which need to be reformatted or manipulated in some way before 121being displayed to the user. 122The suffix may contain the normal shell globbing characters (NOT 123including curly braces 124.Pq Dq {} ) . 125The rest of the line must be a shell command line, the standard 126output of which is the manual page in a format which may be directly 127displayed to the user. 128Any occurrences of the string 129.Dq %s 130in the shell command line will 131be replaced by the name of the file which is being reformatted. 132.It _crunch 133The 134.Dq _crunch 135section is used by catman to know how to crunch cat pages 136which originally were compressed man pages: The first field lists a suffix 137which indicates what kind of compression were used to compress the man page. 138The rest of the line must be a shell command line, used to compress the 139formatted pages. 140.It _subdir 141The list (in search order) of subdirectories which will be searched in 142any directory named with a trailing slash 143.Pq Dq / 144character. 145This list is also used when a path is specified to the 146.Xr man 1 147utility by the user, using the 148.Ev MANPATH 149environment variable or the 150.Fl M 151and 152.Fl m 153options. 154.It _suffix 155Man file names, regardless of their format are expected to end in 156a 157.Dq \.* 158pattern, i.e. a 159.Dq \&\. 160followed by some suffix. 161Each field of a _suffix line is a suffix which indicates 162files which do not need to be reformatted or manipulated 163in any way, but which may be directly displayed to the user. 164Each suffix may contain the normal shell globbing characters (NOT 165including curly braces 166.Pq Dq {} ) . 167.It _version 168The version of the configuration file. 169.It _whatdb 170The full pathname (not just a directory path) for a database to be used 171by the 172.Xr apropos 1 173and 174.Xr whatis 1 175commands. 176The pathname may contain the normal shell globbing characters, 177including curly braces 178.Pq Dq {} ; 179to escape a shell globbing character, 180precede it with a backslash 181.Pq Dq \e . 182.El 183.Pp 184Multiple specifications for all types of lines are cumulative and the 185entries are used in the order listed in the file; multiple entries may 186be listed per line, as well. 187.Pp 188Empty lines or lines whose first non-whitespace character is a hash 189mark 190.Pq Dq # 191are ignored. 192.Sh FILES 193.Bl -tag -width /etc/man.conf -compact 194.It Pa /etc/man.conf 195Standard manual directory search path. 196.El 197.Sh EXAMPLES 198Given the following 199.Nm 200file: 201.Bd -literal -offset indent 202_version BSD.2 203_subdir cat[123] 204_suffix .0 205_build .[1-9] nroff -man %s 206_build .tbl tbl %s | nroff -man 207_default /usr/share/man/ 208sect3 /usr/share/man/{old/,}cat3 209.Ed 210.Pp 211By default, the command 212.Dq Li man mktemp 213will search for 214.Dq mktemp.\*[Lt]any_digit\*[Gt] 215and 216.Dq mktemp.tbl 217in the directories 218.Dq Pa /usr/share/man/cat1 , 219.Dq Pa /usr/share/man/cat2 , 220and 221.Dq Pa /usr/share/man/cat3 . 222If on a machine of type 223.Dq vax , 224the subdirectory 225.Dq vax 226in each 227directory would be searched as well, before the directory was 228searched. 229.Pp 230If 231.Dq mktemp.tbl 232was found first, the command 233.Dq Li tbl \*[Lt]manual page\*[Gt] | nroff -man 234would be run to build a man page for display to the user. 235.Pp 236The command 237.Dq Li man sect3 mktemp 238would search the directories 239.Dq Pa /usr/share/man/old/cat3 240and 241.Dq Pa /usr/share/man/cat3 , 242in that order, for 243the mktemp manual page. 244If a subdirectory with the same name as the current machine type 245existed in any of them, it would be searched as well, before each 246of them were searched. 247.Sh SEE ALSO 248.Xr apropos 1 , 249.Xr machine 1 , 250.Xr man 1 , 251.Xr whatis 1 , 252.Xr whereis 1 , 253.Xr fnmatch 3 , 254.Xr glob 3 , 255.Xr makewhatis 8 256