1.\" $NetBSD: man.conf.5,v 1.21 2011/12/27 13:15:55 apb 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 December 27, 2011 33.Dt MAN.CONF 5 34.Os 35.Sh NAME 36.Nm man.conf 37.Nd configuration file for manual pages 38.Sh DESCRIPTION 39The 40.Nm 41file contains the default configuration used by 42.Xr man 1 , 43.Xr apropos 1 , 44.Xr whatis 1 , 45.Xr catman 8 , 46and 47.Xr makewhatis 8 48to find manual pages and information about manual pages (e.g. the 49whatis database). 50.Pp 51Manual pages are located by searching an ordered set of directories 52called the 53.Dq man path 54for a file that matches the name of the requested page. 55Each directory in the search path usually has a set of subdirectories 56in it (though this is not required). 57When subdirectories are used, there are normally two subdirectories 58for each section of the manual. 59One subdirectory contains formatted copies of that section's manual 60pages that can be directly displayed to a terminal, while the other 61section subdirectory contains unformatted copies of the pages (see 62.Xr nroff 1 63and 64.Xr mdoc 7 ) . 65Formatted manual pages are normally named with a trailing 66.Dq \.0 67suffix. 68.Pp 69The 70.Nm 71file contains comment and configuration lines. 72Comment lines start with the 73.Dq # 74character. 75Blank lines are also treated as comment lines. 76Configuration lines consist of a configuration keyword followed by a 77configuration string. 78There are two types of configuration keywords: control keywords and 79section keywords. 80Control keywords must start with the 81.Dq _ 82character. 83The following control keywords are currently defined: 84.Bl -tag -width "_version" 85.It _build 86identifies the set of suffixes used for manual pages that must be 87formatted for display and the command that should be used to format 88them. 89Manual file names, regardless of their format, are expected to end in a 90.Dq \.* 91pattern, i.e. a 92.Dq \&\. 93followed by some suffix. 94The first field of a _build line contains a man page suffix specification. 95The suffix specification may contain the normal shell globbing characters 96(NOT including curly braces 97.Pq Dq {} ) . 98The rest of the _build line is a shell command line whose standard 99output is a formatted manual page that can be directly displayed to 100the user. 101There should be exactly one occurrence of the string 102.Dq %s 103in the shell command line, and it will 104be replaced by the name of the file which is being formatted. 105.It _crunch 106used by 107.Xr catman 8 108to determine how to crunch formatted pages 109which originally were compressed man pages: The first field lists a suffix 110which indicates what kind of compression were used to compress the man page. 111The rest of the line must be a shell command line, used to compress the 112formatted pages. 113There should be exactly one occurrence of the string 114.Dq %s 115in the shell command line, and it will 116be replaced by the name of the output file. 117.It _default 118contains the system-wide default man path used to search for man pages. 119.It _subdir 120contains the list (in search order) of section subdirectories which will 121be searched in any man path directory named with a trailing slash 122.Pq Dq / 123character. 124This list is also used, even if there is no trailing slash character, 125when a path is specified to the 126.Xr man 1 127utility by the user, by the 128.Ev MANPATH 129environment variable, or by the 130.Fl M 131and 132.Fl m 133options. 134.It _suffix 135identifies the set of suffixes used for formatted man pages 136(the 137.Dq \.0 138suffix is normally used here). 139Formatted man pages can be directly displayed to the user. 140Each suffix may contain the normal shell globbing characters (NOT 141including curly braces 142.Pq Dq {} ) . 143.It _version 144contains the version of the configuration file. 145.It _whatdb 146defines the full pathname (not just a directory path) for a database to 147be used 148by the 149.Xr apropos 1 150and 151.Xr whatis 1 152commands. 153The pathname may contain the normal shell globbing characters, 154including curly braces 155.Pq Dq {} ; 156to escape a shell globbing character, 157precede it with a backslash 158.Pq Dq \e . 159.El 160.Pp 161Section configuration lines in 162.Nm 163consist of a section keyword naming the section and a configuration 164string that defines the directory or subdirectory path that the section's 165manual pages are located in. 166The path may contain the normal shell globbing characters, 167including curly braces 168.Pq Dq {} ; 169to escape a shell globbing character, 170precede it with a backslash 171.Pq Dq \e . 172Section keywords must not start with the 173.Dq _ 174character. 175.Pp 176A section path may contain either a list of absolute directories or 177a list of or relative directories (but not both). 178Relative directory paths are treated as a list of subdirectories that 179are appended to the current man path directory being searched. 180Section configuration lines with absolute directory paths (starting with 181.Dq / ) 182completely replace the current man search path directory with their 183content. 184.Pp 185Section configuration lines with absolute directory paths ending 186with a trailing slash character are expected to contain subdirectories 187of manual pages, (see the keyword 188.Dq _subdir 189above). 190The 191.Dq _subdir 192subdirectory list is not applied to absolute section directories 193if there is no trailing slash. 194.Pp 195In addition to the above rules, the 196.Xr man 1 197command also always checks in each directory that it searches for 198a subdirectory with the same name as the current machine type. 199If the machine-specific directory is found, it is also searched. 200This allows the manual to contain machine-specific man pages. 201Note that the machine subdirectory does not need to be specified 202in the 203.Nm 204file. 205.Pp 206Multiple specifications for all types of 207.Nm 208configuration lines are 209cumulative and the entries are used in the order listed in the file; 210multiple entries may be listed per line, as well. 211.Sh FILES 212.Bl -tag -width /etc/man.conf -compact 213.It Pa /etc/man.conf 214Standard manual configuration file. 215.El 216.Sh EXAMPLES 217Given the following 218.Nm 219file: 220.Bd -literal -offset indent 221_version BSD.2 222_subdir cat[123] 223_suffix .0 224_build .[1-9] nroff -man %s 225_build .tbl tbl %s | nroff -man 226_default /usr/share/man/ 227sect3 /usr/share/man/{old/,}cat3 228.Ed 229.Pp 230By default, the command 231.Dq Li man mktemp 232will search for 233.Dq mktemp.\*[Lt]any_digit\*[Gt] 234and 235.Dq mktemp.tbl 236in the directories 237.Dq Pa /usr/share/man/cat1 , 238.Dq Pa /usr/share/man/cat2 , 239and 240.Dq Pa /usr/share/man/cat3 . 241If on a machine of type 242.Dq vax , 243the subdirectory 244.Dq vax 245in each 246directory would be searched as well, before the directory was 247searched. 248.Pp 249If 250.Dq mktemp.tbl 251was found first, the command 252.Dq Li tbl \*[Lt]manual page\*[Gt] | nroff -man 253would be run to build a man page for display to the user. 254.Pp 255The command 256.Dq Li man sect3 mktemp 257would search the directories 258.Dq Pa /usr/share/man/old/cat3 259and 260.Dq Pa /usr/share/man/cat3 , 261in that order, for 262the mktemp manual page. 263If a subdirectory with the same name as the current machine type 264existed in any of them, it would be searched as well, before each 265of them were searched. 266.Sh SEE ALSO 267.Xr apropos 1 , 268.Xr machine 1 , 269.Xr man 1 , 270.Xr whatis 1 , 271.Xr whereis 1 , 272.Xr fnmatch 3 , 273.Xr glob 3 , 274.Xr catman 8 , 275.Xr makewhatis 8 276