Annotation of src/usr.bin/man/man.conf.5, Revision 1.1
1.1 ! deraadt 1: .\" Copyright (c) 1989, 1991, 1993
! 2: .\" The Regents of the University of California. All rights reserved.
! 3: .\"
! 4: .\" Redistribution and use in source and binary forms, with or without
! 5: .\" modification, are permitted provided that the following conditions
! 6: .\" are met:
! 7: .\" 1. Redistributions of source code must retain the above copyright
! 8: .\" notice, this list of conditions and the following disclaimer.
! 9: .\" 2. Redistributions in binary form must reproduce the above copyright
! 10: .\" notice, this list of conditions and the following disclaimer in the
! 11: .\" documentation and/or other materials provided with the distribution.
! 12: .\" 3. All advertising materials mentioning features or use of this software
! 13: .\" must display the following acknowledgement:
! 14: .\" This product includes software developed by the University of
! 15: .\" California, Berkeley and its contributors.
! 16: .\" 4. Neither the name of the University nor the names of its contributors
! 17: .\" may be used to endorse or promote products derived from this software
! 18: .\" without specific prior written permission.
! 19: .\"
! 20: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
! 21: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
! 22: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
! 23: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
! 24: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
! 25: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
! 26: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
! 27: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
! 28: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
! 29: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
! 30: .\" SUCH DAMAGE.
! 31: .\"
! 32: .\" @(#)man.conf.5 8.5 (Berkeley) 1/2/94
! 33: .\"
! 34: .Dd January 2, 1994
! 35: .Dt MAN.CONF 5
! 36: .Os
! 37: .Sh NAME
! 38: .Nm man.conf
! 39: .Nd configuration file for
! 40: .Xr man 1
! 41: .Sh DESCRIPTION
! 42: The
! 43: .Xr man 1 ,
! 44: .Xr apropos 1 ,
! 45: and
! 46: .Xr whatis 1
! 47: commands
! 48: search for manual pages or their database files as specified by the
! 49: .Nm man.conf
! 50: file.
! 51: Manual pages are normally expected to be preformatted (see
! 52: .Xr nroff 1 )
! 53: and named with a trailing ``.0''.
! 54: .Pp
! 55: The
! 56: .Nm man.conf
! 57: file contains two types of lines.
! 58: .Pp
! 59: The first type of line is a ``section'' line, which contains a
! 60: section name followed by one or more directory paths.
! 61: The directory paths may contain the normal shell globbing characters,
! 62: including curly braces (``{}''); to escape a shell globbing character,
! 63: precede it with a backslash (``\e'').
! 64: Lines in this format specify that manual pages for the section
! 65: may be found in the following directories.
! 66: .Pp
! 67: Directories named with a trailing slash character (``/'') are expected
! 68: to contain subdirectories of manual pages, (see the keyword ``_subdir''
! 69: below) instead of manual pages.
! 70: These subdirectories are searched instead of the directory.
! 71: .Pp
! 72: Before searching any directory for a manual page, the
! 73: .Xr man 1
! 74: command always searches the subdirectory with the same name
! 75: as the current machine type, if it exists.
! 76: No specification of these subdirectories is necessary in the
! 77: .Nm man.conf
! 78: file.
! 79: .Pp
! 80: Section names are unrestricted except for the reserved words specified
! 81: below; in general, you should avoid anything with a leading underscore
! 82: (``_'') to avoid future incompatibilities.
! 83: .Pp
! 84: The section named ``_default'' is the list of directories that will
! 85: be searched if no section is specified by the user.
! 86: .Pp
! 87: The second type of line is preceded with a ``keyword''.
! 88: The possible keywords and their meanings are as follows:
! 89: .Pp
! 90: .Bl -tag -width "_version"
! 91: .It _build
! 92: Man file names, regardless of their format, are expected to end in
! 93: a ``.*'' pattern, i.e. a ``.'' followed by some suffix.
! 94: The first field of a _build line lists a suffix which indicates
! 95: files which need to be reformated or manipulated in some way before
! 96: being displayed to the user.
! 97: The suffix may contain the normal shell globbing characters (NOT
! 98: including curly braces (``{}'')).
! 99: The rest of the line must be a shell command line, the standard
! 100: output of which is the manual page in a format which may be directly
! 101: displayed to the user.
! 102: Any occurrences of the string ``%s'' in the shell command line will
! 103: be replaced by the name of the file which is being reformatted.
! 104: .It _subdir
! 105: The list (in search order) of subdirectories which will be searched in
! 106: any directory named with a trailing slash (``/'') character.
! 107: This list is also used when a path is specified to the
! 108: .Xr man 1
! 109: utility by the user, using the
! 110: .Ev MANPATH
! 111: environment variable or the
! 112: .Fl M
! 113: and
! 114: .Fl m
! 115: options.
! 116: .It _suffix
! 117: Man file names, regardless of their format are expected to end in
! 118: a ``.*'' pattern, i.e. a ``.'' followed by some suffix.
! 119: Each field of a _suffix line is a suffix which indicates
! 120: files which do not need to be reformatted or manipulated
! 121: in any way, but which may be directly displayed to the user.
! 122: Each suffix may contain the normal shell globbing characters (NOT
! 123: including curly braces (``{}'')).
! 124: .It _version
! 125: The version of the configuration file.
! 126: .It _whatdb
! 127: The full pathname (not just a directory path) for a database to be used
! 128: by the
! 129: .Xr apropos 1
! 130: and
! 131: .Xr whatis 1
! 132: commands.
! 133: .El
! 134: .Pp
! 135: Multiple specifications for all types of lines are cumulative and the
! 136: entries are used in the order listed in the file; multiple entries may
! 137: be listed per line, as well.
! 138: .Pp
! 139: Empty lines or lines whose first non-whitespace character is a hash
! 140: mark (``#'') are ignored.
! 141: .Sh EXAMPLES
! 142: Given the following
! 143: .Nm man.conf
! 144: file:
! 145: .Bd -literal -offset indent
! 146: _version BSD.2
! 147: _subdir cat[123]
! 148: _suffix .0
! 149: _build .[1-9] nroff -man %s
! 150: _build .tbl tbl %s | nroff -man
! 151: _default /usr/share/man/
! 152: sect3 /usr/share/man/{old/,}cat3
! 153: .Ed
! 154: .Pp
! 155: By default, the command
! 156: .Dq Li man mktemp
! 157: will search for
! 158: ``mktemp.<any_digit>'' and ``mktemp.tbl''
! 159: in the directories
! 160: .Dq Pa /usr/share/man/cat1 ,
! 161: .Dq Pa /usr/share/man/cat2 ,
! 162: and
! 163: .Dq Pa /usr/share/man/cat3 .
! 164: If on a machine of type ``vax'', the subdirectory ``vax'' in each
! 165: directory would be searched as well, before the directory was
! 166: searched.
! 167: .Pp
! 168: If ``mktemp.tbl'' was found first, the command
! 169: .Dq Li tbl <manual page> | nroff -man
! 170: would be run to build a man page for display to the user.
! 171: .Pp
! 172: The command
! 173: .Dq Li man sect3 mktemp
! 174: would search the directories
! 175: .Dq Pa /usr/share/man/old/cat3
! 176: and
! 177: .Dq Pa /usr/share/man/cat3 ,
! 178: in that order, for
! 179: the mktemp manual page.
! 180: If a subdirectory with the same name as the current machine type
! 181: existed in any of them, it would be searched as well, before each
! 182: of them were searched.
! 183: .Sh FILES
! 184: .Bl -tag -width /etc/man.conf -compact
! 185: .It Pa /etc/man.conf
! 186: Standard manual directory search path.
! 187: .El
! 188: .Sh SEE ALSO
! 189: .Xr apropos 1 ,
! 190: .Xr machine 1 ,
! 191: .Xr man 1 ,
! 192: .Xr whatis 1 ,
! 193: .Xr whereis 1 ,
! 194: .Xr fnmatch 3 ,
! 195: .Xr glob 3