1.\" $NetBSD: man.conf.5,v 1.20 2007/02/10 19:27:39 reed 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 April 10, 2006 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. 101Any occurrences of the string 102.Dq %s 103in the shell command line 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. 113.It _default 114contains the system-wide default man path used to search for man pages. 115.It _subdir 116contains the list (in search order) of section subdirectories which will 117be searched in any man path directory named with a trailing slash 118.Pq Dq / 119character. 120This list is also used, even if there is no trailing slash character, 121when a path is specified to the 122.Xr man 1 123utility by the user, by the 124.Ev MANPATH 125environment variable, or by the 126.Fl M 127and 128.Fl m 129options. 130.It _suffix 131identifies the set of suffixes used for formatted man pages 132(the 133.Dq \.0 134suffix is normally used here). 135Formatted man pages can be directly displayed to the user. 136Each suffix may contain the normal shell globbing characters (NOT 137including curly braces 138.Pq Dq {} ) . 139.It _version 140contains the version of the configuration file. 141.It _whatdb 142defines the full pathname (not just a directory path) for a database to 143be used 144by the 145.Xr apropos 1 146and 147.Xr whatis 1 148commands. 149The pathname may contain the normal shell globbing characters, 150including curly braces 151.Pq Dq {} ; 152to escape a shell globbing character, 153precede it with a backslash 154.Pq Dq \e . 155.El 156.Pp 157Section configuration lines in 158.Nm 159consist of a section keyword naming the section and a configuration 160string that defines the directory or subdirectory path that the section's 161manual pages are located in. 162The path may contain the normal shell globbing characters, 163including curly braces 164.Pq Dq {} ; 165to escape a shell globbing character, 166precede it with a backslash 167.Pq Dq \e . 168Section keywords must not start with the 169.Dq _ 170character. 171.Pp 172A section path may contain either a list of absolute directories or 173a list of or relative directories (but not both). 174Relative directory paths are treated as a list of subdirectories that 175are appended to the current man path directory being searched. 176Section configuration lines with absolute directory paths (starting with 177.Dq / ) 178completely replace the current man search path directory with their 179content. 180.Pp 181Section configuration lines with absolute directory paths ending 182with a trailing slash character are expected to contain subdirectories 183of manual pages, (see the keyword 184.Dq _subdir 185above). 186The 187.Dq _subdir 188subdirectory list is not applied to absolute section directories 189if there is no trailing slash. 190.Pp 191In addition to the above rules, the 192.Xr man 1 193command also always checks in each directory that it searches for 194a subdirectory with the same name as the current machine type. 195If the machine-specific directory is found, it is also searched. 196This allows the manual to contain machine-specific man pages. 197Note that the machine subdirectory does not need to be specified 198in the 199.Nm 200file. 201.Pp 202Multiple specifications for all types of 203.Nm 204configuration lines are 205cumulative and the entries are used in the order listed in the file; 206multiple entries may be listed per line, as well. 207.Sh FILES 208.Bl -tag -width /etc/man.conf -compact 209.It Pa /etc/man.conf 210Standard manual configuration file. 211.El 212.Sh EXAMPLES 213Given the following 214.Nm 215file: 216.Bd -literal -offset indent 217_version BSD.2 218_subdir cat[123] 219_suffix .0 220_build .[1-9] nroff -man %s 221_build .tbl tbl %s | nroff -man 222_default /usr/share/man/ 223sect3 /usr/share/man/{old/,}cat3 224.Ed 225.Pp 226By default, the command 227.Dq Li man mktemp 228will search for 229.Dq mktemp.\*[Lt]any_digit\*[Gt] 230and 231.Dq mktemp.tbl 232in the directories 233.Dq Pa /usr/share/man/cat1 , 234.Dq Pa /usr/share/man/cat2 , 235and 236.Dq Pa /usr/share/man/cat3 . 237If on a machine of type 238.Dq vax , 239the subdirectory 240.Dq vax 241in each 242directory would be searched as well, before the directory was 243searched. 244.Pp 245If 246.Dq mktemp.tbl 247was found first, the command 248.Dq Li tbl \*[Lt]manual page\*[Gt] | nroff -man 249would be run to build a man page for display to the user. 250.Pp 251The command 252.Dq Li man sect3 mktemp 253would search the directories 254.Dq Pa /usr/share/man/old/cat3 255and 256.Dq Pa /usr/share/man/cat3 , 257in that order, for 258the mktemp manual page. 259If a subdirectory with the same name as the current machine type 260existed in any of them, it would be searched as well, before each 261of them were searched. 262.Sh SEE ALSO 263.Xr apropos 1 , 264.Xr machine 1 , 265.Xr man 1 , 266.Xr whatis 1 , 267.Xr whereis 1 , 268.Xr fnmatch 3 , 269.Xr glob 3 , 270.Xr catman 8 , 271.Xr makewhatis 8 272