1.\" $NetBSD: man.conf.5,v 1.24 2013/06/28 10:13:18 wiz 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 October 5, 2013 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 XXmachineX 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.It _ Ns Aq machine 160Defines additional paths to be searched for the particular 161.Dv machine 162whose literal value is taken from 163.Xr uname 1 164.Fl m . 165For example on an 166.Dv amd64 , 167.Dv _amd64 168is used. 169.El 170.Pp 171Section configuration lines in 172.Nm 173consist of a section keyword naming the section and a configuration 174string that defines the directory or subdirectory path that the section's 175manual pages are located in. 176The path 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 . 182Section keywords must not start with the 183.Dq _ 184character. 185.Pp 186A section path may contain either a list of absolute directories or 187a list of or relative directories (but not both). 188Relative directory paths are treated as a list of subdirectories that 189are appended to the current man path directory being searched. 190Section configuration lines with absolute directory paths (starting with 191.Dq / ) 192completely replace the current man search path directory with their 193content. 194.Pp 195Section configuration lines with absolute directory paths ending 196with a trailing slash character are expected to contain subdirectories 197of manual pages, (see the keyword 198.Dq _subdir 199above). 200The 201.Dq _subdir 202subdirectory list is not applied to absolute section directories 203if there is no trailing slash. 204.Pp 205In addition to the above rules, the 206.Xr man 1 207command also always checks in each directory that it searches for 208a subdirectory with the same name as the current machine type. 209If the machine-specific directory is found, it is also searched. 210This allows the manual to contain machine-specific man pages. 211Note that the machine subdirectory does not need to be specified 212in the 213.Nm 214file. 215.Pp 216Multiple specifications for all types of 217.Nm 218configuration lines are 219cumulative and the entries are used in the order listed in the file; 220multiple entries may be listed per line, as well. 221.Sh FILES 222.Bl -tag -width /etc/man.conf -compact 223.It Pa /etc/man.conf 224Standard manual configuration file. 225.El 226.Sh EXAMPLES 227Given the following 228.Nm 229file: 230.Bd -literal -offset indent 231_version BSD.2 232_subdir cat[123] 233_suffix .0 234_build .[1-9] nroff -man %s 235_build .tbl tbl %s | nroff -man 236_i386 x86 237_default /usr/share/man/ 238sect3 /usr/share/man/{old/,}cat3 239.Ed 240.Pp 241By default, the command 242.Dq Li man mktemp 243will search for 244.Dq mktemp. Ns Aq any_digit 245and 246.Dq mktemp.tbl 247in the directories 248.Dq Pa /usr/share/man/cat1 , 249.Dq Pa /usr/share/man/cat2 , 250and 251.Dq Pa /usr/share/man/cat3 . 252If on a machine of type 253.Dq vax , 254the subdirectory 255.Dq vax 256in each 257directory would be searched as well, before the directory was 258searched. 259.Pp 260If 261.Dq mktemp.tbl 262was found first, the command 263.Dq Li tbl Ao manual page Ac | nroff -man 264would be run to build a man page for display to the user. 265.Pp 266The command 267.Dq Li man sect3 mktemp 268would search the directories 269.Dq Pa /usr/share/man/old/cat3 270and 271.Dq Pa /usr/share/man/cat3 , 272in that order, for 273the mktemp manual page. 274If a subdirectory with the same name as the current machine type 275existed in any of them, it would be searched as well, before each 276of them were searched. 277.Sh SEE ALSO 278.Xr apropos 1 , 279.Xr machine 1 , 280.Xr man 1 , 281.Xr whatis 1 , 282.Xr whereis 1 , 283.Xr fnmatch 3 , 284.Xr glob 3 , 285.Xr catman 8 , 286.Xr makewhatis 8 287