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

Annotation of mandoc/man.1, Revision 1.8

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

CVSweb