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

Annotation of mandoc/man.1, Revision 1.40

1.40    ! schwarze    1: .\"    $Id: man.1,v 1.39 2020/06/17 19:42:32 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.37      schwarze    6: .\" Copyright (c) 2010, 2011, 2014-2020 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.40    ! schwarze   34: .Dd $Mdocdate: June 17 2020 $
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
                     44: .Op Fl M Ar path
                     45: .Op Fl m Ar path
                     46: .Op Fl S Ar subsection
1.28      schwarze   47: .Op Oo Fl s Oc Ar section
1.1       schwarze   48: .Ar name ...
                     49: .Sh DESCRIPTION
                     50: The
                     51: .Nm
                     52: utility
                     53: displays the
1.36      schwarze   54: manual page entitled
1.1       schwarze   55: .Ar name .
                     56: Pages may be selected according to
                     57: a specific category
                     58: .Pq Ar section
                     59: or
                     60: machine architecture
                     61: .Pq Ar subsection .
                     62: .Pp
                     63: The options are as follows:
                     64: .Bl -tag -width Ds
                     65: .It Fl a
1.18      schwarze   66: Display all matching manual pages.
1.1       schwarze   67: .It Fl C Ar file
                     68: Use the specified
                     69: .Ar file
                     70: instead of the default configuration file.
                     71: This permits users to configure their own manual environment.
                     72: See
                     73: .Xr man.conf 5
                     74: for a description of the contents of this file.
                     75: .It Fl c
                     76: Copy the manual page to the standard output instead of using
1.40    ! schwarze   77: .Xr less 1
1.1       schwarze   78: to paginate it.
                     79: This is done by default if the standard output is not a terminal device.
1.30      schwarze   80: .Pp
                     81: When using
                     82: .Fl c ,
                     83: most terminal devices are unable to show the markup.
                     84: To print the output of
                     85: .Nm
                     86: to the terminal with markup but without using a pager, pipe it to
                     87: .Xr ul 1 .
                     88: To remove the markup, pipe the output to
                     89: .Xr col 1
                     90: .Fl b
                     91: instead.
1.2       schwarze   92: .It Fl f
1.1       schwarze   93: A synonym for
                     94: .Xr whatis 1 .
1.2       schwarze   95: It searches for
                     96: .Ar name
                     97: in manual page names and displays the header lines from all matching pages.
                     98: The search is case insensitive and matches whole words only.
1.20      schwarze   99: .It Fl h
                    100: Display only the SYNOPSIS lines of the requested manual pages.
                    101: Implies
                    102: .Fl a
                    103: and
                    104: .Fl c .
1.2       schwarze  105: .It Fl k
1.1       schwarze  106: A synonym for
                    107: .Xr apropos 1 .
1.2       schwarze  108: Instead of
                    109: .Ar name ,
                    110: an expression can be provided using the syntax described in the
                    111: .Xr apropos 1
                    112: manual.
                    113: By default, it displays the header lines of all matching pages.
1.4       schwarze  114: .It Fl l
                    115: A synonym for
1.33      schwarze  116: .Xr mandoc 1 .
1.4       schwarze  117: The
                    118: .Ar name
                    119: arguments are interpreted as filenames.
                    120: No search is done and
                    121: .Ar file ,
                    122: .Ar path ,
                    123: .Ar section ,
1.27      schwarze  124: .Ar subsection ,
1.4       schwarze  125: and
1.27      schwarze  126: .Fl w
1.4       schwarze  127: are ignored.
1.33      schwarze  128: This option implies
                    129: .Fl a .
1.1       schwarze  130: .It Fl M Ar path
1.36      schwarze  131: Override the list of directories to search for manual pages.
1.1       schwarze  132: The supplied
                    133: .Ar path
                    134: must be a colon
                    135: .Pq Ql \&:
                    136: separated list of directories.
1.36      schwarze  137: This option also overrides the environment variable
                    138: .Ev MANPATH
                    139: and any directories specified in the
                    140: .Xr man.conf 5
                    141: file.
1.1       schwarze  142: .It Fl m Ar path
1.36      schwarze  143: Augment the list of directories to search for manual pages.
1.1       schwarze  144: The supplied
                    145: .Ar path
                    146: must be a colon
                    147: .Pq Ql \&:
                    148: separated list of directories.
1.36      schwarze  149: These directories will be searched before those specified using the
1.1       schwarze  150: .Fl M
1.36      schwarze  151: option, the
1.1       schwarze  152: .Ev MANPATH
1.36      schwarze  153: environment variable, the
                    154: .Xr man.conf 5
                    155: file, or the default directories.
1.1       schwarze  156: .It Fl S Ar subsection
1.25      schwarze  157: Only show pages for the specified
1.1       schwarze  158: .Xr machine 1
                    159: architecture.
                    160: .Ar subsection
                    161: is case insensitive.
                    162: .Pp
                    163: By default manual pages for all architectures are installed.
                    164: Therefore this option can be used to view pages for one
                    165: architecture whilst using another.
                    166: .Pp
                    167: This option overrides the
                    168: .Ev MACHINE
                    169: environment variable.
1.39      schwarze  170: .Tg s
1.17      schwarze  171: .It Oo Fl s Oc Ar section
                    172: Only select manuals from the specified
                    173: .Ar section .
1.1       schwarze  174: The currently available sections are:
                    175: .Pp
                    176: .Bl -tag -width "localXXX" -offset indent -compact
                    177: .It 1
                    178: General commands
                    179: .Pq tools and utilities .
                    180: .It 2
                    181: System calls and error numbers.
                    182: .It 3
1.17      schwarze  183: Library functions.
1.1       schwarze  184: .It 3p
                    185: .Xr perl 1
                    186: programmer's reference guide.
                    187: .It 4
                    188: Device drivers.
                    189: .It 5
                    190: File formats.
                    191: .It 6
                    192: Games.
                    193: .It 7
1.17      schwarze  194: Miscellaneous information.
1.1       schwarze  195: .It 8
                    196: System maintenance and operation commands.
                    197: .It 9
                    198: Kernel internals.
                    199: .El
                    200: .It Fl w
1.25      schwarze  201: List the pathnames of all matching manual pages instead of displaying
                    202: any of them.
1.37      schwarze  203: If no
                    204: .Ar name
                    205: is given, list the directories that would be searched.
1.1       schwarze  206: .El
1.26      schwarze  207: .Pp
                    208: The options
                    209: .Fl IKOTW
                    210: are also supported and are documented in
                    211: .Xr mandoc 1 .
1.27      schwarze  212: The options
                    213: .Fl fkl
                    214: are mutually exclusive and override each other.
1.1       schwarze  215: .Pp
1.36      schwarze  216: The search starts with the
                    217: .Fl m
                    218: argument if provided, then continues with the
                    219: .Fl M
                    220: argument, the
                    221: .Ev MANPATH
                    222: variable, the
                    223: .Ic manpath
                    224: entries in the
                    225: .Xr man.conf 5
                    226: file, or with
                    227: .Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man
                    228: by default.
                    229: Within each of these, directories are searched in the order provided.
                    230: Within each directory, the search proceeds according to the following
                    231: list of sections: 1, 8, 6, 2, 3, 5, 7, 4, 9, 3p.
                    232: The first match found is shown.
1.1       schwarze  233: .Pp
1.35      schwarze  234: The
                    235: .Xr mandoc.db 5
                    236: database is used for looking up manual page entries.
                    237: In cases where the database is absent, outdated, or corrupt,
                    238: .Nm
                    239: falls back to looking for files called
                    240: .Ar name . Ns Ar section .
1.1       schwarze  241: If both a formatted and an unformatted version of the same manual page,
                    242: for example
                    243: .Pa cat1/foo.0
                    244: and
                    245: .Pa man1/foo.1 ,
1.24      schwarze  246: exist in the same directory, only the unformatted version is used.
1.35      schwarze  247: The database is kept up to date with
                    248: .Xr makewhatis 8 ,
                    249: which is run by the
                    250: .Xr weekly 8
                    251: maintenance script.
1.36      schwarze  252: .Pp
                    253: Guidelines for writing
                    254: man pages can be found in
                    255: .Xr mdoc 7 .
1.1       schwarze  256: .Sh ENVIRONMENT
                    257: .Bl -tag -width MANPATHX
                    258: .It Ev MACHINE
                    259: As some manual pages are intended only for specific architectures,
                    260: .Nm
                    261: searches any subdirectories,
                    262: with the same name as the current architecture,
                    263: in every directory which it searches.
                    264: Machine specific areas are checked before general areas.
                    265: The current machine type may be overridden by setting the environment
                    266: variable
                    267: .Ev MACHINE
                    268: to the name of a specific architecture,
                    269: or with the
                    270: .Fl S
                    271: option.
                    272: .Ev MACHINE
                    273: is case insensitive.
                    274: .It Ev MANPAGER
                    275: Any non-empty value of the environment variable
                    276: .Ev MANPAGER
1.23      schwarze  277: is used instead of the standard pagination program,
1.40    ! schwarze  278: .Xr less 1 .
1.15      schwarze  279: If
                    280: .Xr less 1
                    281: is used, the interactive
                    282: .Ic :t
                    283: command can be used to go to the definitions of various terms, for
                    284: example command line options, command modifiers, internal commands,
1.19      schwarze  285: environment variables, function names, preprocessor macros,
                    286: .Xr errno 2
                    287: values, and some other emphasized words.
                    288: Some terms may have defining text at more than one place.
                    289: In that case, the
                    290: .Xr less 1
                    291: interactive commands
                    292: .Ic t
                    293: and
                    294: .Ic T
                    295: can be used to move to the next and to the previous place providing
                    296: information about the term last searched for with
                    297: .Ic :t .
1.34      schwarze  298: The
                    299: .Fl O Cm tag Ns Op = Ns Ar term
                    300: option documented in the
                    301: .Xr mandoc 1
                    302: manual opens a manual page at the definition of a specific
                    303: .Ar term
                    304: rather than at the beginning.
1.1       schwarze  305: .It Ev MANPATH
1.36      schwarze  306: Override the standard search path which is either specified in
                    307: .Xr man.conf 5
                    308: or the default path.
                    309: The format of
1.1       schwarze  310: .Ev MANPATH
1.36      schwarze  311: is a colon
1.1       schwarze  312: .Pq Ql \&:
                    313: separated list of directories.
1.36      schwarze  314: Invalid directories are ignored.
1.23      schwarze  315: Overridden by
                    316: .Fl M ,
                    317: ignored if
                    318: .Fl l
                    319: is specified.
                    320: .Pp
                    321: If
                    322: .Ev MANPATH
1.36      schwarze  323: begins with a colon, it is appended to the standard path;
                    324: if it ends with a colon, it is prepended to the standard path;
1.23      schwarze  325: or if it contains two adjacent colons,
1.36      schwarze  326: the standard path is inserted between the colons.
1.1       schwarze  327: .It Ev PAGER
                    328: Specifies the pagination program to use when
                    329: .Ev MANPAGER
                    330: is not defined.
                    331: If neither PAGER nor MANPAGER is defined,
1.40    ! schwarze  332: .Xr less 1
1.23      schwarze  333: is used.
1.1       schwarze  334: .El
                    335: .Sh FILES
                    336: .Bl -tag -width /etc/man.conf -compact
                    337: .It Pa /etc/man.conf
1.36      schwarze  338: default
                    339: .Nm
                    340: configuration file
1.1       schwarze  341: .El
                    342: .Sh EXIT STATUS
                    343: .Ex -std man
1.25      schwarze  344: See
                    345: .Xr mandoc 1
                    346: for details.
1.31      schwarze  347: .Sh EXAMPLES
                    348: Format a page for pasting extracts into an email message \(em
                    349: avoid printing any UTF-8 characters, reduce the width to ease
                    350: quoting in replies, and remove markup:
                    351: .Pp
                    352: .Dl $ man -T ascii -O width=65 pledge | col -b
                    353: .Pp
                    354: Read a typeset page in a PDF viewer:
                    355: .Pp
                    356: .Dl $ MANPAGER=mupdf man -T pdf lpd
1.1       schwarze  357: .Sh SEE ALSO
                    358: .Xr apropos 1 ,
1.30      schwarze  359: .Xr col 1 ,
                    360: .Xr mandoc 1 ,
                    361: .Xr ul 1 ,
1.1       schwarze  362: .Xr whereis 1 ,
                    363: .Xr man.conf 5 ,
1.30      schwarze  364: .Xr mdoc 7
1.1       schwarze  365: .Sh STANDARDS
                    366: The
                    367: .Nm
                    368: utility is compliant with the
                    369: .St -p1003.1-2008
                    370: specification.
                    371: .Pp
                    372: The flags
1.13      schwarze  373: .Op Fl aCcfhIKlMmOSsTWw ,
1.1       schwarze  374: as well as the environment variables
                    375: .Ev MACHINE ,
                    376: .Ev MANPAGER ,
                    377: and
                    378: .Ev MANPATH ,
                    379: are extensions to that specification.
                    380: .Sh HISTORY
                    381: A
                    382: .Nm
                    383: command first appeared in
1.38      schwarze  384: .At v2 .
1.1       schwarze  385: .Pp
                    386: The
                    387: .Fl w
                    388: option first appeared in
                    389: .At v7 ;
                    390: .Fl f
                    391: and
                    392: .Fl k
                    393: in
                    394: .Bx 4 ;
                    395: .Fl M
                    396: in
                    397: .Bx 4.3 ;
                    398: .Fl a
                    399: in
                    400: .Bx 4.3 Tahoe ;
                    401: .Fl c
                    402: and
                    403: .Fl m
                    404: in
                    405: .Bx 4.3 Reno ;
                    406: .Fl h
                    407: in
                    408: .Bx 4.3 Net/2 ;
                    409: .Fl C
                    410: in
                    411: .Nx 1.0 ;
                    412: .Fl s
                    413: and
                    414: .Fl S
                    415: in
1.21      schwarze  416: .Ox 2.3 ;
                    417: and
                    418: .Fl I ,
                    419: .Fl K ,
                    420: .Fl l ,
                    421: .Fl O ,
                    422: and
                    423: .Fl W
                    424: in
                    425: .Ox 5.7 .
                    426: The
                    427: .Fl T
                    428: option first appeared in
                    429: .At III
                    430: and was also added in
                    431: .Ox 5.7 .

CVSweb