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

Annotation of mandoc/man.1, Revision 1.5

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

CVSweb