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

Annotation of mandoc/man.1, Revision 1.18

1.18    ! schwarze    1: .\"    $Id: man.1,v 1.17 2016/07/01 20:24:04 schwarze Exp $
1.1       schwarze    2: .\"
                      3: .\" Copyright (c) 1989, 1990, 1993
                      4: .\"    The Regents of the University of California.  All rights reserved.
1.2       schwarze    5: .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
1.11      schwarze    6: .\" Copyright (c) 2010, 2011, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org>
1.1       schwarze    7: .\"
                      8: .\" Redistribution and use in source and binary forms, with or without
                      9: .\" modification, are permitted provided that the following conditions
                     10: .\" are met:
                     11: .\" 1. Redistributions of source code must retain the above copyright
                     12: .\"    notice, this list of conditions and the following disclaimer.
                     13: .\" 2. Redistributions in binary form must reproduce the above copyright
                     14: .\"    notice, this list of conditions and the following disclaimer in the
                     15: .\"    documentation and/or other materials provided with the distribution.
                     16: .\" 3. 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.1      8.2 (Berkeley) 1/2/94
                     33: .\"
1.18    ! schwarze   34: .Dd $Mdocdate: July 1 2016 $
1.1       schwarze   35: .Dt MAN 1
                     36: .Os
                     37: .Sh NAME
                     38: .Nm man
                     39: .Nd display manual pages
                     40: .Sh SYNOPSIS
                     41: .Nm man
1.13      schwarze   42: .Op Fl acfhklw
1.1       schwarze   43: .Op Fl C Ar file
1.8       schwarze   44: .Op Fl I Cm os Ns = Ns Ar name
                     45: .Op Fl K Ar encoding
1.1       schwarze   46: .Op Fl M Ar path
                     47: .Op Fl m Ar path
1.8       schwarze   48: .Op Fl O Ar option Ns = Ns Ar value
1.1       schwarze   49: .Op Fl S Ar subsection
                     50: .Op Fl s Ar section
1.8       schwarze   51: .Op Fl T Ar output
                     52: .Op Fl W Ar level
1.1       schwarze   53: .Op Ar section
                     54: .Ar name ...
                     55: .Sh DESCRIPTION
                     56: The
                     57: .Nm
                     58: utility
                     59: displays the
                     60: manual pages entitled
                     61: .Ar name .
                     62: Pages may be selected according to
                     63: a specific category
                     64: .Pq Ar section
                     65: or
                     66: machine architecture
                     67: .Pq Ar subsection .
                     68: .Pp
                     69: The options are as follows:
                     70: .Bl -tag -width Ds
                     71: .It Fl a
1.18    ! schwarze   72: Display all matching manual pages.
        !            73: Normally, only the first page found is displayed.
1.1       schwarze   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.8       schwarze   99: .It Fl I Cm os Ns = Ns Ar name
                    100: Override the default operating system
                    101: .Ar name
                    102: for the
                    103: .Xr mdoc 7
                    104: .Ic \&Os
1.10      schwarze  105: and for the
                    106: .Xr man 7
                    107: .Ic \&TH
1.8       schwarze  108: macro.
1.1       schwarze  109: .It Fl h
1.5       schwarze  110: Display only the SYNOPSIS lines of the requested manual pages.
                    111: Implies
1.7       schwarze  112: .Fl a
                    113: and
                    114: .Fl c .
1.8       schwarze  115: .It Fl K Ar encoding
                    116: Specify the input encoding.
                    117: The supported
                    118: .Ar encoding
                    119: arguments are
                    120: .Cm us-ascii ,
                    121: .Cm iso-8859-1 ,
                    122: and
                    123: .Cm utf-8 .
                    124: By default, the encoding is automatically detected as described in the
                    125: .Xr mandoc 1
                    126: manual.
1.2       schwarze  127: .It Fl k
1.1       schwarze  128: A synonym for
                    129: .Xr apropos 1 .
1.2       schwarze  130: Instead of
                    131: .Ar name ,
                    132: an expression can be provided using the syntax described in the
                    133: .Xr apropos 1
                    134: manual.
                    135: By default, it displays the header lines of all matching pages.
1.4       schwarze  136: This overrides any earlier
                    137: .Fl f
                    138: and
                    139: .Fl l
                    140: options.
                    141: .It Fl l
                    142: A synonym for
                    143: .Xr mandoc 1
                    144: .Fl a .
                    145: The
                    146: .Ar name
                    147: arguments are interpreted as filenames.
                    148: No search is done and
                    149: .Ar file ,
                    150: .Ar path ,
                    151: .Ar section ,
                    152: and
                    153: .Ar subsection
                    154: are ignored.
                    155: This overrides any earlier
                    156: .Fl f ,
                    157: .Fl k ,
                    158: and
                    159: .Fl w
                    160: options.
1.1       schwarze  161: .It Fl M Ar path
                    162: Override the list of standard directories which
                    163: .Nm
                    164: searches for manual pages.
                    165: The supplied
                    166: .Ar path
                    167: must be a colon
                    168: .Pq Ql \&:
                    169: separated list of directories.
                    170: This search path may also be set using the environment variable
                    171: .Ev MANPATH .
                    172: .It Fl m Ar path
                    173: Augment the list of standard directories which
                    174: .Nm
                    175: searches for manual pages.
                    176: The supplied
                    177: .Ar path
                    178: must be a colon
                    179: .Pq Ql \&:
                    180: separated list of directories.
                    181: These directories will be searched before the standard directories or
                    182: the directories specified using the
                    183: .Fl M
                    184: option or the
                    185: .Ev MANPATH
                    186: environment variable.
1.8       schwarze  187: .It Fl O Ar option Ns = Ns Ar value
                    188: Comma-separated output options.
                    189: For each output format, the available options are described in the
                    190: .Xr mandoc 1
                    191: manual.
1.1       schwarze  192: .It Fl S Ar subsection
                    193: Restricts the directories that
                    194: .Nm
                    195: will search to those of a specific
                    196: .Xr machine 1
                    197: architecture.
                    198: .Ar subsection
                    199: is case insensitive.
                    200: .Pp
                    201: By default manual pages for all architectures are installed.
                    202: Therefore this option can be used to view pages for one
                    203: architecture whilst using another.
                    204: .Pp
                    205: This option overrides the
                    206: .Ev MACHINE
                    207: environment variable.
1.17      schwarze  208: .It Oo Fl s Oc Ar section
                    209: Only select manuals from the specified
                    210: .Ar section .
1.1       schwarze  211: The currently available sections are:
                    212: .Pp
                    213: .Bl -tag -width "localXXX" -offset indent -compact
                    214: .It 1
                    215: General commands
                    216: .Pq tools and utilities .
                    217: .It 2
                    218: System calls and error numbers.
                    219: .It 3
1.17      schwarze  220: Library functions.
1.1       schwarze  221: .It 3p
                    222: .Xr perl 1
                    223: programmer's reference guide.
                    224: .It 4
                    225: Device drivers.
                    226: .It 5
                    227: File formats.
                    228: .It 6
                    229: Games.
                    230: .It 7
1.17      schwarze  231: Miscellaneous information.
1.1       schwarze  232: .It 8
                    233: System maintenance and operation commands.
                    234: .It 9
                    235: Kernel internals.
                    236: .El
1.8       schwarze  237: .It Fl T Ar output
                    238: Select the output format.
                    239: The default is
                    240: .Cm locale .
                    241: The other output modes
                    242: .Cm ascii ,
                    243: .Cm html ,
                    244: .Cm lint ,
                    245: .Cm man ,
                    246: .Cm pdf ,
                    247: .Cm ps ,
                    248: .Cm tree ,
                    249: and
                    250: .Cm utf8
                    251: are described in the
                    252: .Xr mandoc 1
                    253: manual.
                    254: .It Fl W Ar level
                    255: Specify the minimum message
                    256: .Ar level
                    257: to be reported on the standard error output and to affect the exit status.
                    258: The
                    259: .Ar level
                    260: can be
1.12      schwarze  261: .Cm warning ,
                    262: .Cm error ,
1.8       schwarze  263: or
1.12      schwarze  264: .Cm unsupp ;
1.8       schwarze  265: .Cm all
                    266: is an alias for
                    267: .Cm warning .
1.11      schwarze  268: By default,
                    269: .Nm
                    270: is silent.
1.8       schwarze  271: See the
                    272: .Xr mandoc 1
                    273: manual for details.
1.1       schwarze  274: .It Fl w
                    275: List the pathnames of the manual pages which
                    276: .Nm
                    277: would display for the specified
                    278: .Ar section
                    279: and
                    280: .Ar name
                    281: combination.
                    282: .El
                    283: .Pp
1.2       schwarze  284: Guidelines for writing
1.1       schwarze  285: man pages can be found in
                    286: .Xr mdoc 7 .
                    287: .Pp
                    288: If both a formatted and an unformatted version of the same manual page,
                    289: for example
                    290: .Pa cat1/foo.0
                    291: and
                    292: .Pa man1/foo.1 ,
                    293: exist in the same directory, and at least one of them is selected,
                    294: only the newer one is used.
                    295: However, if both the
                    296: .Fl a
                    297: and the
                    298: .Fl w
                    299: options are specified, both file names are printed.
                    300: .Sh ENVIRONMENT
                    301: .Bl -tag -width MANPATHX
                    302: .It Ev MACHINE
                    303: As some manual pages are intended only for specific architectures,
                    304: .Nm
                    305: searches any subdirectories,
                    306: with the same name as the current architecture,
                    307: in every directory which it searches.
                    308: Machine specific areas are checked before general areas.
                    309: The current machine type may be overridden by setting the environment
                    310: variable
                    311: .Ev MACHINE
                    312: to the name of a specific architecture,
                    313: or with the
                    314: .Fl S
                    315: option.
                    316: .Ev MACHINE
                    317: is case insensitive.
                    318: .It Ev MANPAGER
                    319: Any non-empty value of the environment variable
                    320: .Ev MANPAGER
                    321: will be used instead of the standard pagination program,
                    322: .Xr more 1 .
1.15      schwarze  323: If
                    324: .Xr less 1
                    325: is used, the interactive
                    326: .Ic :t
                    327: command can be used to go to the definitions of various terms, for
                    328: example command line options, command modifiers, internal commands,
                    329: and environment variables.
1.1       schwarze  330: .It Ev MANPATH
                    331: The standard search path used by
                    332: .Nm
                    333: may be overridden by specifying a path in the
                    334: .Ev MANPATH
                    335: environment
                    336: variable.
                    337: The format of the path is a colon
                    338: .Pq Ql \&:
                    339: separated list of directories.
                    340: .It Ev PAGER
                    341: Specifies the pagination program to use when
                    342: .Ev MANPAGER
                    343: is not defined.
                    344: If neither PAGER nor MANPAGER is defined,
1.14      schwarze  345: .Xr more 1
                    346: .Fl s
1.1       schwarze  347: will be used.
                    348: .El
                    349: .Sh FILES
                    350: .Bl -tag -width /etc/man.conf -compact
                    351: .It Pa /etc/man.conf
                    352: default man configuration file
                    353: .El
                    354: .Sh EXIT STATUS
                    355: .Ex -std man
                    356: .Sh SEE ALSO
                    357: .Xr apropos 1 ,
                    358: .Xr intro 1 ,
                    359: .Xr whatis 1 ,
                    360: .Xr whereis 1 ,
                    361: .Xr intro 2 ,
                    362: .Xr intro 3 ,
                    363: .Xr intro 4 ,
                    364: .Xr intro 5 ,
                    365: .Xr man.conf 5 ,
                    366: .Xr intro 6 ,
                    367: .Xr intro 7 ,
                    368: .Xr mdoc 7 ,
                    369: .Xr intro 8 ,
                    370: .Xr intro 9
                    371: .Sh STANDARDS
                    372: The
                    373: .Nm
                    374: utility is compliant with the
                    375: .St -p1003.1-2008
                    376: specification.
                    377: .Pp
                    378: The flags
1.13      schwarze  379: .Op Fl aCcfhIKlMmOSsTWw ,
1.1       schwarze  380: as well as the environment variables
                    381: .Ev MACHINE ,
                    382: .Ev MANPAGER ,
                    383: and
                    384: .Ev MANPATH ,
                    385: are extensions to that specification.
                    386: .Sh HISTORY
                    387: A
                    388: .Nm
                    389: command first appeared in
                    390: .At v3 .
                    391: .Pp
                    392: The
                    393: .Fl w
                    394: option first appeared in
                    395: .At v7 ;
                    396: .Fl f
                    397: and
                    398: .Fl k
                    399: in
                    400: .Bx 4 ;
                    401: .Fl M
                    402: in
                    403: .Bx 4.3 ;
                    404: .Fl a
                    405: in
                    406: .Bx 4.3 Tahoe ;
                    407: .Fl c
                    408: and
                    409: .Fl m
                    410: in
                    411: .Bx 4.3 Reno ;
                    412: .Fl h
                    413: in
                    414: .Bx 4.3 Net/2 ;
                    415: .Fl C
                    416: in
                    417: .Nx 1.0 ;
                    418: and
                    419: .Fl s
                    420: and
                    421: .Fl S
                    422: in
                    423: .Ox 2.3 .

CVSweb