[BACK]Return to man.1 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/man.1, Revision 1.4

1.4     ! schwarze    1: .\"    $Id: man.1,v 1.3 2014/08/21 02:38:24 schwarze Exp $
1.1       schwarze    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.
1.2       schwarze    6: .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
                      7: .\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
1.1       schwarze    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: .\"
1.2       schwarze   35: .Dd $Mdocdate: August 21 2014 $
1.1       schwarze   36: .Dt MAN 1
                     37: .Os
                     38: .Sh NAME
                     39: .Nm man
                     40: .Nd display manual pages
                     41: .Sh SYNOPSIS
                     42: .Nm man
1.4     ! schwarze   43: .Op Fl acfhklVw
1.1       schwarze   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.
1.2       schwarze   87: .It Fl f
1.1       schwarze   88: A synonym for
                     89: .Xr whatis 1 .
1.2       schwarze   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.
1.4     ! schwarze   94: This overrides any earlier
        !            95: .Fl k
        !            96: and
        !            97: .Fl l
        !            98: options.
1.1       schwarze   99: .It Fl h
                    100: Display only the
                    101: .Dq SYNOPSIS
                    102: lines of the requested manual pages.
1.2       schwarze  103: .It Fl k
1.1       schwarze  104: A synonym for
                    105: .Xr apropos 1 .
1.2       schwarze  106: Instead of
                    107: .Ar name ,
                    108: an expression can be provided using the syntax described in the
                    109: .Xr apropos 1
                    110: manual.
                    111: By default, it displays the header lines of all matching pages.
1.4     ! schwarze  112: This overrides any earlier
        !           113: .Fl f
        !           114: and
        !           115: .Fl l
        !           116: options.
        !           117: .It Fl l
        !           118: A synonym for
        !           119: .Xr mandoc 1
        !           120: .Fl a .
        !           121: The
        !           122: .Ar name
        !           123: arguments are interpreted as filenames.
        !           124: No search is done and
        !           125: .Ar file ,
        !           126: .Ar path ,
        !           127: .Ar section ,
        !           128: and
        !           129: .Ar subsection
        !           130: are ignored.
        !           131: This overrides any earlier
        !           132: .Fl f ,
        !           133: .Fl k ,
        !           134: and
        !           135: .Fl w
        !           136: options.
1.1       schwarze  137: .It Fl M Ar path
                    138: Override the list of standard directories which
                    139: .Nm
                    140: searches for manual pages.
                    141: The supplied
                    142: .Ar path
                    143: must be a colon
                    144: .Pq Ql \&:
                    145: separated list of directories.
                    146: This search path may also be set using the environment variable
                    147: .Ev MANPATH .
                    148: The subdirectories to be searched, and their search order,
                    149: are specified by the
                    150: .Dq _subdir
                    151: line in the
                    152: .Nm
                    153: configuration file.
                    154: .It Fl m Ar path
                    155: Augment the list of standard directories which
                    156: .Nm
                    157: searches for manual pages.
                    158: The supplied
                    159: .Ar path
                    160: must be a colon
                    161: .Pq Ql \&:
                    162: separated list of directories.
                    163: These directories will be searched before the standard directories or
                    164: the directories specified using the
                    165: .Fl M
                    166: option or the
                    167: .Ev MANPATH
                    168: environment variable.
                    169: The subdirectories to be searched, and their search order,
                    170: are specified by the
                    171: .Dq _subdir
                    172: line in the
                    173: .Nm
                    174: configuration file.
                    175: .It Fl S Ar subsection
                    176: Restricts the directories that
                    177: .Nm
                    178: will search to those of a specific
                    179: .Xr machine 1
                    180: architecture.
                    181: .Ar subsection
                    182: is case insensitive.
                    183: .Pp
                    184: By default manual pages for all architectures are installed.
                    185: Therefore this option can be used to view pages for one
                    186: architecture whilst using another.
                    187: .Pp
                    188: This option overrides the
                    189: .Ev MACHINE
                    190: environment variable.
                    191: .It Xo
                    192: .Op Fl s
                    193: .Ar section
                    194: .Xc
                    195: Restricts the directories that
                    196: .Nm
                    197: will search to a specific section.
                    198: The currently available sections are:
                    199: .Pp
                    200: .Bl -tag -width "localXXX" -offset indent -compact
                    201: .It 1
                    202: General commands
                    203: .Pq tools and utilities .
                    204: .It 2
                    205: System calls and error numbers.
                    206: .It 3
                    207: Libraries.
                    208: .It 3f
                    209: Fortran programmer's reference guide.
                    210: .It 3p
                    211: .Xr perl 1
                    212: programmer's reference guide.
                    213: .It 4
                    214: Device drivers.
                    215: .It 5
                    216: File formats.
                    217: .It 6
                    218: Games.
                    219: .It 7
                    220: Miscellaneous.
                    221: .It 8
                    222: System maintenance and operation commands.
                    223: .It 9
                    224: Kernel internals.
                    225: .It X11
                    226: An alias for X11R6.
                    227: .It X11R6
                    228: X Window System.
                    229: .It local
                    230: Pages located in
                    231: .Pa /usr/local .
                    232: .It n
                    233: Tcl/Tk commands.
                    234: .El
                    235: .Pp
                    236: The
                    237: .Nm
                    238: configuration file,
                    239: .Xr man.conf 5 ,
                    240: specifies the possible
                    241: .Ar section
                    242: values, and their search order.
                    243: Additional sections may be specified.
1.4     ! schwarze  244: .It Fl V
        !           245: Print version and exit.
1.1       schwarze  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
1.3       schwarze  255: .Pp
                    256: The
                    257: .Nm
                    258: utility also supports the options
                    259: .Fl IOTW
                    260: described in the
                    261: .Xr mandoc 1
                    262: manual.
1.1       schwarze  263: .Pp
1.2       schwarze  264: Guidelines for writing
1.1       schwarze  265: man pages can be found in
                    266: .Xr mdoc 7 .
                    267: .Pp
                    268: If both a formatted and an unformatted version of the same manual page,
                    269: for example
                    270: .Pa cat1/foo.0
                    271: and
                    272: .Pa man1/foo.1 ,
                    273: exist in the same directory, and at least one of them is selected,
                    274: only the newer one is used.
                    275: However, if both the
                    276: .Fl a
                    277: and the
                    278: .Fl w
                    279: options are specified, both file names are printed.
                    280: .Sh ENVIRONMENT
                    281: .Bl -tag -width MANPATHX
                    282: .It Ev MACHINE
                    283: As some manual pages are intended only for specific architectures,
                    284: .Nm
                    285: searches any subdirectories,
                    286: with the same name as the current architecture,
                    287: in every directory which it searches.
                    288: Machine specific areas are checked before general areas.
                    289: The current machine type may be overridden by setting the environment
                    290: variable
                    291: .Ev MACHINE
                    292: to the name of a specific architecture,
                    293: or with the
                    294: .Fl S
                    295: option.
                    296: .Ev MACHINE
                    297: is case insensitive.
                    298: .It Ev MANPAGER
                    299: Any non-empty value of the environment variable
                    300: .Ev MANPAGER
                    301: will be used instead of the standard pagination program,
                    302: .Xr more 1 .
                    303: .It Ev MANPATH
                    304: The standard search path used by
                    305: .Nm
                    306: may be overridden by specifying a path in the
                    307: .Ev MANPATH
                    308: environment
                    309: variable.
                    310: The format of the path is a colon
                    311: .Pq Ql \&:
                    312: separated list of directories.
                    313: The subdirectories to be searched, as well as their search order,
                    314: are specified by the
                    315: .Dq _subdir
                    316: line in the
                    317: .Nm
                    318: configuration file.
                    319: .It Ev PAGER
                    320: Specifies the pagination program to use when
                    321: .Ev MANPAGER
                    322: is not defined.
                    323: If neither PAGER nor MANPAGER is defined,
                    324: .Pa /usr/bin/more Fl s
                    325: will be used.
                    326: .El
                    327: .Sh FILES
                    328: .Bl -tag -width /etc/man.conf -compact
                    329: .It Pa /etc/man.conf
                    330: default man configuration file
                    331: .El
                    332: .Sh EXIT STATUS
                    333: .Ex -std man
                    334: .Sh SEE ALSO
                    335: .Xr apropos 1 ,
                    336: .Xr intro 1 ,
                    337: .Xr whatis 1 ,
                    338: .Xr whereis 1 ,
                    339: .Xr intro 2 ,
                    340: .Xr intro 3 ,
                    341: .Xr intro 4 ,
                    342: .Xr intro 5 ,
                    343: .Xr man.conf 5 ,
                    344: .Xr intro 6 ,
                    345: .Xr intro 7 ,
                    346: .Xr mdoc 7 ,
                    347: .Xr intro 8 ,
                    348: .Xr intro 9
                    349: .Sh STANDARDS
                    350: The
                    351: .Nm
                    352: utility is compliant with the
                    353: .St -p1003.1-2008
                    354: specification.
                    355: .Pp
                    356: The flags
                    357: .Op Fl aCcfhMmSsw ,
                    358: as well as the environment variables
                    359: .Ev MACHINE ,
                    360: .Ev MANPAGER ,
                    361: and
                    362: .Ev MANPATH ,
                    363: are extensions to that specification.
                    364: .Sh HISTORY
                    365: A
                    366: .Nm
                    367: command first appeared in
                    368: .At v3 .
                    369: .Pp
                    370: The
                    371: .Fl w
                    372: option first appeared in
                    373: .At v7 ;
                    374: .Fl f
                    375: and
                    376: .Fl k
                    377: in
                    378: .Bx 4 ;
                    379: .Fl M
                    380: in
                    381: .Bx 4.3 ;
                    382: .Fl a
                    383: in
                    384: .Bx 4.3 Tahoe ;
                    385: .Fl c
                    386: and
                    387: .Fl m
                    388: in
                    389: .Bx 4.3 Reno ;
                    390: .Fl h
                    391: in
                    392: .Bx 4.3 Net/2 ;
                    393: .Fl C
                    394: in
                    395: .Nx 1.0 ;
                    396: and
                    397: .Fl s
                    398: and
                    399: .Fl S
                    400: in
                    401: .Ox 2.3 .

CVSweb