Annotation of mandoc/man.1, Revision 1.1
1.1 ! schwarze 1: .\" $OpenBSD: man.1,v 1.55 2014/04/03 06:15:18 jmc Exp $
! 2: .\"
! 3: .\" Copyright (c) 1989, 1990, 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.1 8.2 (Berkeley) 1/2/94
! 31: .\"
! 32: .Dd $Mdocdate: April 3 2014 $
! 33: .Dt MAN 1
! 34: .Os
! 35: .Sh NAME
! 36: .Nm man
! 37: .Nd display manual pages
! 38: .Sh SYNOPSIS
! 39: .Nm man
! 40: .Op Fl achw
! 41: .Op Fl C Ar file
! 42: .Op Fl M Ar path
! 43: .Op Fl m Ar path
! 44: .Op Fl S Ar subsection
! 45: .Op Fl s Ar section
! 46: .Op Ar section
! 47: .Ar name ...
! 48: .Nm man
! 49: .Fl f Ar command ...
! 50: .Nm man
! 51: .Fl k Ar keyword ...
! 52: .Sh DESCRIPTION
! 53: The
! 54: .Nm
! 55: utility
! 56: displays the
! 57: .Bx
! 58: manual pages entitled
! 59: .Ar name .
! 60: Pages may be selected according to
! 61: a specific category
! 62: .Pq Ar section
! 63: or
! 64: machine architecture
! 65: .Pq Ar subsection .
! 66: .Pp
! 67: The options are as follows:
! 68: .Bl -tag -width Ds
! 69: .It Fl a
! 70: Display all of the manual pages for a specified
! 71: .Ar section
! 72: and
! 73: .Ar name
! 74: combination.
! 75: Normally, only the first manual page found is displayed.
! 76: .It Fl C Ar file
! 77: Use the specified
! 78: .Ar file
! 79: instead of the default configuration file.
! 80: This permits users to configure their own manual environment.
! 81: See
! 82: .Xr man.conf 5
! 83: for a description of the contents of this file.
! 84: .It Fl c
! 85: Copy the manual page to the standard output instead of using
! 86: .Xr more 1
! 87: to paginate it.
! 88: This is done by default if the standard output is not a terminal device.
! 89: .It Fl f Ar command
! 90: A synonym for
! 91: .Xr whatis 1 .
! 92: It looks up a given command and
! 93: gives the header line from the manual page.
! 94: .Ar command
! 95: is case insensitive.
! 96: .It Fl h
! 97: Display only the
! 98: .Dq SYNOPSIS
! 99: lines of the requested manual pages.
! 100: .It Fl k Ar keyword
! 101: A synonym for
! 102: .Xr apropos 1 .
! 103: It shows which manual pages contain instances of any of the given
! 104: keywords in their title line.
! 105: .Ar keyword
! 106: is case insensitive.
! 107: .Pp
! 108: For instance,
! 109: to list all man pages which contain
! 110: .Dq mount
! 111: in the
! 112: .Dq NAME
! 113: line of the man page:
! 114: .Pp
! 115: .Dl $ man -k mount
! 116: .Pp
! 117: Which would produce a list much like this:
! 118: .Bd -literal
! 119: amd (8) \(en automatically mount file systems
! 120: amq (8) \(en automounter query tool
! 121: domountroothooks (9) \(en run all mountroot hooks
! 122: exports (5) \(en define remote mount points for NFS mount requests
! 123: getfsstat (2) \(en get list of all mounted file systems
! 124: getmntinfo (3) \(en get information about mounted file systems
! 125: mount (8) \(en mount file systems
! 126: mount, unmount (2) \(en mount or dismount a filesystem
! 127: mount_cd9660 (8) \(en mount an ISO-9660 filesystem
! 128: mount_ext2fs (8) \(en mount an ext2fs file system
! 129: mount_ffs (8) \(en mount a Berkeley Fast File System
! 130: mount_msdos (8) \(en mount an MS-DOS file system
! 131: mount_nfs (8) \(en mount NFS file systems
! 132: mount_ntfs (8) \(en mount an NTFS file system
! 133: mount_procfs (8) \(en mount the process file system
! 134: mount_udf (8) \(en mount a UDF filesystem
! 135: mount_vnd, vnconfig (8) \(en configure vnode disks
! 136: mountd (8) \(en service remote NFS mount requests
! 137: \&...
! 138: .Ed
! 139: .It Fl M Ar path
! 140: Override the list of standard directories which
! 141: .Nm
! 142: searches for manual pages.
! 143: The supplied
! 144: .Ar path
! 145: must be a colon
! 146: .Pq Ql \&:
! 147: separated list of directories.
! 148: This search path may also be set using the environment variable
! 149: .Ev MANPATH .
! 150: The subdirectories to be searched, and their search order,
! 151: are specified by the
! 152: .Dq _subdir
! 153: line in the
! 154: .Nm
! 155: configuration file.
! 156: .It Fl m Ar path
! 157: Augment the list of standard directories which
! 158: .Nm
! 159: searches for manual pages.
! 160: The supplied
! 161: .Ar path
! 162: must be a colon
! 163: .Pq Ql \&:
! 164: separated list of directories.
! 165: These directories will be searched before the standard directories or
! 166: the directories specified using the
! 167: .Fl M
! 168: option or the
! 169: .Ev MANPATH
! 170: environment variable.
! 171: The subdirectories to be searched, and their search order,
! 172: are specified by the
! 173: .Dq _subdir
! 174: line in the
! 175: .Nm
! 176: configuration file.
! 177: .It Fl S Ar subsection
! 178: Restricts the directories that
! 179: .Nm
! 180: will search to those of a specific
! 181: .Xr machine 1
! 182: architecture.
! 183: .Ar subsection
! 184: is case insensitive.
! 185: .Pp
! 186: By default manual pages for all architectures are installed.
! 187: Therefore this option can be used to view pages for one
! 188: architecture whilst using another.
! 189: .Pp
! 190: This option overrides the
! 191: .Ev MACHINE
! 192: environment variable.
! 193: .It Xo
! 194: .Op Fl s
! 195: .Ar section
! 196: .Xc
! 197: Restricts the directories that
! 198: .Nm
! 199: will search to a specific section.
! 200: The currently available sections are:
! 201: .Pp
! 202: .Bl -tag -width "localXXX" -offset indent -compact
! 203: .It 1
! 204: General commands
! 205: .Pq tools and utilities .
! 206: .It 2
! 207: System calls and error numbers.
! 208: .It 3
! 209: Libraries.
! 210: .It 3f
! 211: Fortran programmer's reference guide.
! 212: .It 3p
! 213: .Xr perl 1
! 214: programmer's reference guide.
! 215: .It 4
! 216: Device drivers.
! 217: .It 5
! 218: File formats.
! 219: .It 6
! 220: Games.
! 221: .It 7
! 222: Miscellaneous.
! 223: .It 8
! 224: System maintenance and operation commands.
! 225: .It 9
! 226: Kernel internals.
! 227: .It X11
! 228: An alias for X11R6.
! 229: .It X11R6
! 230: X Window System.
! 231: .It local
! 232: Pages located in
! 233: .Pa /usr/local .
! 234: .It n
! 235: Tcl/Tk commands.
! 236: .El
! 237: .Pp
! 238: The
! 239: .Nm
! 240: configuration file,
! 241: .Xr man.conf 5 ,
! 242: specifies the possible
! 243: .Ar section
! 244: values, and their search order.
! 245: Additional sections may be specified.
! 246: .It Fl w
! 247: List the pathnames of the manual pages which
! 248: .Nm
! 249: would display for the specified
! 250: .Ar section
! 251: and
! 252: .Ar name
! 253: combination.
! 254: .El
! 255: .Pp
! 256: Guidelines for
! 257: .Ox
! 258: man pages can be found in
! 259: .Xr mdoc 7 .
! 260: .Pp
! 261: If both a formatted and an unformatted version of the same manual page,
! 262: for example
! 263: .Pa cat1/foo.0
! 264: and
! 265: .Pa man1/foo.1 ,
! 266: exist in the same directory, and at least one of them is selected,
! 267: only the newer one is used.
! 268: However, if both the
! 269: .Fl a
! 270: and the
! 271: .Fl w
! 272: options are specified, both file names are printed.
! 273: .Sh ENVIRONMENT
! 274: .Bl -tag -width MANPATHX
! 275: .It Ev MACHINE
! 276: As some manual pages are intended only for specific architectures,
! 277: .Nm
! 278: searches any subdirectories,
! 279: with the same name as the current architecture,
! 280: in every directory which it searches.
! 281: Machine specific areas are checked before general areas.
! 282: The current machine type may be overridden by setting the environment
! 283: variable
! 284: .Ev MACHINE
! 285: to the name of a specific architecture,
! 286: or with the
! 287: .Fl S
! 288: option.
! 289: .Ev MACHINE
! 290: is case insensitive.
! 291: .It Ev MANPAGER
! 292: Any non-empty value of the environment variable
! 293: .Ev MANPAGER
! 294: will be used instead of the standard pagination program,
! 295: .Xr more 1 .
! 296: .It Ev MANPATH
! 297: The standard search path used by
! 298: .Nm
! 299: may be overridden by specifying a path in the
! 300: .Ev MANPATH
! 301: environment
! 302: variable.
! 303: The format of the path is a colon
! 304: .Pq Ql \&:
! 305: separated list of directories.
! 306: The subdirectories to be searched, as well as their search order,
! 307: are specified by the
! 308: .Dq _subdir
! 309: line in the
! 310: .Nm
! 311: configuration file.
! 312: .It Ev PAGER
! 313: Specifies the pagination program to use when
! 314: .Ev MANPAGER
! 315: is not defined.
! 316: If neither PAGER nor MANPAGER is defined,
! 317: .Pa /usr/bin/more Fl s
! 318: will be used.
! 319: .El
! 320: .Sh FILES
! 321: .Bl -tag -width /etc/man.conf -compact
! 322: .It Pa /etc/man.conf
! 323: default man configuration file
! 324: .El
! 325: .Sh EXIT STATUS
! 326: .Ex -std man
! 327: .Sh SEE ALSO
! 328: .Xr apropos 1 ,
! 329: .Xr intro 1 ,
! 330: .Xr whatis 1 ,
! 331: .Xr whereis 1 ,
! 332: .Xr intro 2 ,
! 333: .Xr intro 3 ,
! 334: .Xr intro 4 ,
! 335: .Xr intro 5 ,
! 336: .Xr man.conf 5 ,
! 337: .Xr intro 6 ,
! 338: .Xr intro 7 ,
! 339: .Xr mdoc 7 ,
! 340: .Xr intro 8 ,
! 341: .Xr intro 9
! 342: .Sh STANDARDS
! 343: The
! 344: .Nm
! 345: utility is compliant with the
! 346: .St -p1003.1-2008
! 347: specification.
! 348: .Pp
! 349: The flags
! 350: .Op Fl aCcfhMmSsw ,
! 351: as well as the environment variables
! 352: .Ev MACHINE ,
! 353: .Ev MANPAGER ,
! 354: and
! 355: .Ev MANPATH ,
! 356: are extensions to that specification.
! 357: .Sh HISTORY
! 358: A
! 359: .Nm
! 360: command first appeared in
! 361: .At v3 .
! 362: .Pp
! 363: The
! 364: .Fl w
! 365: option first appeared in
! 366: .At v7 ;
! 367: .Fl f
! 368: and
! 369: .Fl k
! 370: in
! 371: .Bx 4 ;
! 372: .Fl M
! 373: in
! 374: .Bx 4.3 ;
! 375: .Fl a
! 376: in
! 377: .Bx 4.3 Tahoe ;
! 378: .Fl c
! 379: and
! 380: .Fl m
! 381: in
! 382: .Bx 4.3 Reno ;
! 383: .Fl h
! 384: in
! 385: .Bx 4.3 Net/2 ;
! 386: .Fl C
! 387: in
! 388: .Nx 1.0 ;
! 389: and
! 390: .Fl s
! 391: and
! 392: .Fl S
! 393: in
! 394: .Ox 2.3 .
CVSweb