Annotation of src/usr.bin/mandoc/man.1, Revision 1.1
1.1 ! schwarze 1: .\" $Id: man.1,v 1.3 2014/08/21 02:38:24 schwarze Exp $
! 2: .\" $OpenBSD: man.1,v 1.55 2014/04/03 06:15:18 jmc Exp $
! 3: .\"
! 4: .\" Copyright (c) 1989, 1990, 1993
! 5: .\" The Regents of the University of California. All rights reserved.
! 6: .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
! 7: .\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
! 8: .\"
! 9: .\" Redistribution and use in source and binary forms, with or without
! 10: .\" modification, are permitted provided that the following conditions
! 11: .\" are met:
! 12: .\" 1. Redistributions of source code must retain the above copyright
! 13: .\" notice, this list of conditions and the following disclaimer.
! 14: .\" 2. Redistributions in binary form must reproduce the above copyright
! 15: .\" notice, this list of conditions and the following disclaimer in the
! 16: .\" documentation and/or other materials provided with the distribution.
! 17: .\" 3. Neither the name of the University nor the names of its contributors
! 18: .\" may be used to endorse or promote products derived from this software
! 19: .\" without specific prior written permission.
! 20: .\"
! 21: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
! 22: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
! 23: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
! 24: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
! 25: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
! 26: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
! 27: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
! 28: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
! 29: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
! 30: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
! 31: .\" SUCH DAMAGE.
! 32: .\"
! 33: .\" @(#)man.1 8.2 (Berkeley) 1/2/94
! 34: .\"
! 35: .Dd $Mdocdate: August 21 2014 $
! 36: .Dt MAN 1
! 37: .Os
! 38: .Sh NAME
! 39: .Nm man
! 40: .Nd display manual pages
! 41: .Sh SYNOPSIS
! 42: .Nm man
! 43: .Op Fl acfhkw
! 44: .Op Fl C Ar file
! 45: .Op Fl M Ar path
! 46: .Op Fl m Ar path
! 47: .Op Fl S Ar subsection
! 48: .Op Fl s Ar section
! 49: .Op Ar section
! 50: .Ar name ...
! 51: .Sh DESCRIPTION
! 52: The
! 53: .Nm
! 54: utility
! 55: displays the
! 56: manual pages entitled
! 57: .Ar name .
! 58: Pages may be selected according to
! 59: a specific category
! 60: .Pq Ar section
! 61: or
! 62: machine architecture
! 63: .Pq Ar subsection .
! 64: .Pp
! 65: The options are as follows:
! 66: .Bl -tag -width Ds
! 67: .It Fl a
! 68: Display all of the manual pages for a specified
! 69: .Ar section
! 70: and
! 71: .Ar name
! 72: combination.
! 73: Normally, only the first manual page found is displayed.
! 74: .It Fl C Ar file
! 75: Use the specified
! 76: .Ar file
! 77: instead of the default configuration file.
! 78: This permits users to configure their own manual environment.
! 79: See
! 80: .Xr man.conf 5
! 81: for a description of the contents of this file.
! 82: .It Fl c
! 83: Copy the manual page to the standard output instead of using
! 84: .Xr more 1
! 85: to paginate it.
! 86: This is done by default if the standard output is not a terminal device.
! 87: .It Fl f
! 88: A synonym for
! 89: .Xr whatis 1 .
! 90: It searches for
! 91: .Ar name
! 92: in manual page names and displays the header lines from all matching pages.
! 93: The search is case insensitive and matches whole words only.
! 94: .It Fl h
! 95: Display only the
! 96: .Dq SYNOPSIS
! 97: lines of the requested manual pages.
! 98: .It Fl k
! 99: A synonym for
! 100: .Xr apropos 1 .
! 101: Instead of
! 102: .Ar name ,
! 103: an expression can be provided using the syntax described in the
! 104: .Xr apropos 1
! 105: manual.
! 106: By default, it displays the header lines of all matching pages.
! 107: .It Fl M Ar path
! 108: Override the list of standard directories which
! 109: .Nm
! 110: searches for manual pages.
! 111: The supplied
! 112: .Ar path
! 113: must be a colon
! 114: .Pq Ql \&:
! 115: separated list of directories.
! 116: This search path may also be set using the environment variable
! 117: .Ev MANPATH .
! 118: The subdirectories to be searched, and their search order,
! 119: are specified by the
! 120: .Dq _subdir
! 121: line in the
! 122: .Nm
! 123: configuration file.
! 124: .It Fl m Ar path
! 125: Augment the list of standard directories which
! 126: .Nm
! 127: searches for manual pages.
! 128: The supplied
! 129: .Ar path
! 130: must be a colon
! 131: .Pq Ql \&:
! 132: separated list of directories.
! 133: These directories will be searched before the standard directories or
! 134: the directories specified using the
! 135: .Fl M
! 136: option or the
! 137: .Ev MANPATH
! 138: environment variable.
! 139: The subdirectories to be searched, and their search order,
! 140: are specified by the
! 141: .Dq _subdir
! 142: line in the
! 143: .Nm
! 144: configuration file.
! 145: .It Fl S Ar subsection
! 146: Restricts the directories that
! 147: .Nm
! 148: will search to those of a specific
! 149: .Xr machine 1
! 150: architecture.
! 151: .Ar subsection
! 152: is case insensitive.
! 153: .Pp
! 154: By default manual pages for all architectures are installed.
! 155: Therefore this option can be used to view pages for one
! 156: architecture whilst using another.
! 157: .Pp
! 158: This option overrides the
! 159: .Ev MACHINE
! 160: environment variable.
! 161: .It Xo
! 162: .Op Fl s
! 163: .Ar section
! 164: .Xc
! 165: Restricts the directories that
! 166: .Nm
! 167: will search to a specific section.
! 168: The currently available sections are:
! 169: .Pp
! 170: .Bl -tag -width "localXXX" -offset indent -compact
! 171: .It 1
! 172: General commands
! 173: .Pq tools and utilities .
! 174: .It 2
! 175: System calls and error numbers.
! 176: .It 3
! 177: Libraries.
! 178: .It 3f
! 179: Fortran programmer's reference guide.
! 180: .It 3p
! 181: .Xr perl 1
! 182: programmer's reference guide.
! 183: .It 4
! 184: Device drivers.
! 185: .It 5
! 186: File formats.
! 187: .It 6
! 188: Games.
! 189: .It 7
! 190: Miscellaneous.
! 191: .It 8
! 192: System maintenance and operation commands.
! 193: .It 9
! 194: Kernel internals.
! 195: .It X11
! 196: An alias for X11R6.
! 197: .It X11R6
! 198: X Window System.
! 199: .It local
! 200: Pages located in
! 201: .Pa /usr/local .
! 202: .It n
! 203: Tcl/Tk commands.
! 204: .El
! 205: .Pp
! 206: The
! 207: .Nm
! 208: configuration file,
! 209: .Xr man.conf 5 ,
! 210: specifies the possible
! 211: .Ar section
! 212: values, and their search order.
! 213: Additional sections may be specified.
! 214: .It Fl w
! 215: List the pathnames of the manual pages which
! 216: .Nm
! 217: would display for the specified
! 218: .Ar section
! 219: and
! 220: .Ar name
! 221: combination.
! 222: .El
! 223: .Pp
! 224: The
! 225: .Nm
! 226: utility also supports the options
! 227: .Fl IOTW
! 228: described in the
! 229: .Xr mandoc 1
! 230: manual.
! 231: .Pp
! 232: Guidelines for writing
! 233: man pages can be found in
! 234: .Xr mdoc 7 .
! 235: .Pp
! 236: If both a formatted and an unformatted version of the same manual page,
! 237: for example
! 238: .Pa cat1/foo.0
! 239: and
! 240: .Pa man1/foo.1 ,
! 241: exist in the same directory, and at least one of them is selected,
! 242: only the newer one is used.
! 243: However, if both the
! 244: .Fl a
! 245: and the
! 246: .Fl w
! 247: options are specified, both file names are printed.
! 248: .Sh ENVIRONMENT
! 249: .Bl -tag -width MANPATHX
! 250: .It Ev MACHINE
! 251: As some manual pages are intended only for specific architectures,
! 252: .Nm
! 253: searches any subdirectories,
! 254: with the same name as the current architecture,
! 255: in every directory which it searches.
! 256: Machine specific areas are checked before general areas.
! 257: The current machine type may be overridden by setting the environment
! 258: variable
! 259: .Ev MACHINE
! 260: to the name of a specific architecture,
! 261: or with the
! 262: .Fl S
! 263: option.
! 264: .Ev MACHINE
! 265: is case insensitive.
! 266: .It Ev MANPAGER
! 267: Any non-empty value of the environment variable
! 268: .Ev MANPAGER
! 269: will be used instead of the standard pagination program,
! 270: .Xr more 1 .
! 271: .It Ev MANPATH
! 272: The standard search path used by
! 273: .Nm
! 274: may be overridden by specifying a path in the
! 275: .Ev MANPATH
! 276: environment
! 277: variable.
! 278: The format of the path is a colon
! 279: .Pq Ql \&:
! 280: separated list of directories.
! 281: The subdirectories to be searched, as well as their search order,
! 282: are specified by the
! 283: .Dq _subdir
! 284: line in the
! 285: .Nm
! 286: configuration file.
! 287: .It Ev PAGER
! 288: Specifies the pagination program to use when
! 289: .Ev MANPAGER
! 290: is not defined.
! 291: If neither PAGER nor MANPAGER is defined,
! 292: .Pa /usr/bin/more Fl s
! 293: will be used.
! 294: .El
! 295: .Sh FILES
! 296: .Bl -tag -width /etc/man.conf -compact
! 297: .It Pa /etc/man.conf
! 298: default man configuration file
! 299: .El
! 300: .Sh EXIT STATUS
! 301: .Ex -std man
! 302: .Sh SEE ALSO
! 303: .Xr apropos 1 ,
! 304: .Xr intro 1 ,
! 305: .Xr whatis 1 ,
! 306: .Xr whereis 1 ,
! 307: .Xr intro 2 ,
! 308: .Xr intro 3 ,
! 309: .Xr intro 4 ,
! 310: .Xr intro 5 ,
! 311: .Xr man.conf 5 ,
! 312: .Xr intro 6 ,
! 313: .Xr intro 7 ,
! 314: .Xr mdoc 7 ,
! 315: .Xr intro 8 ,
! 316: .Xr intro 9
! 317: .Sh STANDARDS
! 318: The
! 319: .Nm
! 320: utility is compliant with the
! 321: .St -p1003.1-2008
! 322: specification.
! 323: .Pp
! 324: The flags
! 325: .Op Fl aCcfhMmSsw ,
! 326: as well as the environment variables
! 327: .Ev MACHINE ,
! 328: .Ev MANPAGER ,
! 329: and
! 330: .Ev MANPATH ,
! 331: are extensions to that specification.
! 332: .Sh HISTORY
! 333: A
! 334: .Nm
! 335: command first appeared in
! 336: .At v3 .
! 337: .Pp
! 338: The
! 339: .Fl w
! 340: option first appeared in
! 341: .At v7 ;
! 342: .Fl f
! 343: and
! 344: .Fl k
! 345: in
! 346: .Bx 4 ;
! 347: .Fl M
! 348: in
! 349: .Bx 4.3 ;
! 350: .Fl a
! 351: in
! 352: .Bx 4.3 Tahoe ;
! 353: .Fl c
! 354: and
! 355: .Fl m
! 356: in
! 357: .Bx 4.3 Reno ;
! 358: .Fl h
! 359: in
! 360: .Bx 4.3 Net/2 ;
! 361: .Fl C
! 362: in
! 363: .Nx 1.0 ;
! 364: and
! 365: .Fl s
! 366: and
! 367: .Fl S
! 368: in
! 369: .Ox 2.3 .