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

Annotation of mandoc/apropos.1, Revision 1.29

1.29    ! schwarze    1: .\"    $Id: apropos.1,v 1.28 2014/04/18 10:30:37 schwarze Exp $
1.1       kristaps    2: .\"
1.17      kristaps    3: .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
1.25      schwarze    4: .\" Copyright (c) 2011, 2012, 2014 Ingo Schwarze <schwarze@openbsd.org>
1.1       kristaps    5: .\"
                      6: .\" Permission to use, copy, modify, and distribute this software for any
                      7: .\" purpose with or without fee is hereby granted, provided that the above
                      8: .\" copyright notice and this permission notice appear in all copies.
                      9: .\"
                     10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
                     11: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
                     12: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
                     13: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     14: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
                     15: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
                     16: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
                     17: .\"
1.28      schwarze   18: .Dd $Mdocdate: April 18 2014 $
1.1       kristaps   19: .Dt APROPOS 1
                     20: .Os
                     21: .Sh NAME
1.19      kristaps   22: .Nm apropos ,
                     23: .Nm whatis
1.5       kristaps   24: .Nd search manual page databases
1.1       kristaps   25: .Sh SYNOPSIS
                     26: .Nm
1.13      schwarze   27: .Op Fl C Ar file
1.20      schwarze   28: .Op Fl M Ar path
                     29: .Op Fl m Ar path
1.24      schwarze   30: .Op Fl O Ar outkey
1.3       kristaps   31: .Op Fl S Ar arch
                     32: .Op Fl s Ar section
1.13      schwarze   33: .Ar expression ...
1.1       kristaps   34: .Sh DESCRIPTION
                     35: The
1.19      kristaps   36: .Nm apropos
                     37: and
                     38: .Nm whatis
                     39: utilities query manual page databases generated by
1.28      schwarze   40: .Xr makewhatis 8 ,
1.27      schwarze   41: evaluating
1.4       kristaps   42: .Ar expression
1.5       kristaps   43: for each file in each database.
1.27      schwarze   44: By default, it displays the names, section numbers, and description lines
                     45: of all matching manuals.
1.16      kristaps   46: .Pp
                     47: By default,
                     48: .Nm
                     49: searches for
1.28      schwarze   50: .Xr makewhatis 8
1.16      kristaps   51: databases in the default paths stipulated by
1.27      schwarze   52: .Xr man 1
                     53: and uses case-insensitive substring matching
                     54: .Pq the Cm = No operator
1.23      schwarze   55: over manual names and descriptions
                     56: .Pq the Li \&Nm No and Li \&Nd No macro keys .
                     57: Multiple terms imply pairwise
                     58: .Fl o .
1.19      kristaps   59: .Nm whatis
                     60: maps terms only to case-sensitive manual names.
1.16      kristaps   61: .Pp
1.1       kristaps   62: Its arguments are as follows:
                     63: .Bl -tag -width Ds
1.13      schwarze   64: .It Fl C Ar file
                     65: Specify an alternative configuration
                     66: .Ar file
                     67: in
                     68: .Xr man.conf 5
                     69: format.
1.20      schwarze   70: .It Fl M Ar path
1.7       kristaps   71: Use the colon-separated path instead of the default list of paths
                     72: searched for
1.28      schwarze   73: .Xr makewhatis 8
1.7       kristaps   74: databases.
                     75: Invalid paths, or paths without manual databases, are ignored.
1.20      schwarze   76: .It Fl m Ar path
1.9       schwarze   77: Prepend the colon-separated paths to the list of paths searched
1.6       kristaps   78: for
1.28      schwarze   79: .Xr makewhatis 8
1.5       kristaps   80: databases.
1.6       kristaps   81: Invalid paths, or paths without manual databases, are ignored.
1.24      schwarze   82: .It Fl O Ar outkey
                     83: Show the values associated with the key
                     84: .Ar outkey
                     85: instead of the manual descriptions.
1.3       kristaps   86: .It Fl S Ar arch
1.23      schwarze   87: Restrict the search to pages for the specified
                     88: .Xr machine 1
                     89: architecture.
                     90: .Ar arch
                     91: is case insensitive.
                     92: By default, pages for all architectures are shown.
                     93: .It Fl s Ar section
                     94: Restrict the search to the specified section of the manual.
                     95: By default, pages from all sections are shown.
1.1       kristaps   96: See
                     97: .Xr man 1
1.23      schwarze   98: for a listing of sections.
1.4       kristaps   99: .El
                    100: .Pp
1.23      schwarze  101: An
1.4       kristaps  102: .Ar expression
1.23      schwarze  103: consists of search terms joined by logical operators
                    104: .Fl a
                    105: .Pq and
                    106: and
                    107: .Fl o
                    108: .Pq or .
                    109: The
                    110: .Fl a
                    111: operator has precedence over
                    112: .Fl o
                    113: and both are evaluated left-to-right.
                    114: .Bl -tag -width Ds
                    115: .It \&( Ar expr No \&)
                    116: True if the subexpression
                    117: .Ar expr
                    118: is true.
                    119: .It Ar expr1 Fl a Ar expr2
                    120: True if both
                    121: .Ar expr1
                    122: and
                    123: .Ar expr2
                    124: are true (logical
1.27      schwarze  125: .Sq and ) .
1.23      schwarze  126: .It Ar expr1 Oo Fl o Oc Ar expr2
                    127: True if
                    128: .Ar expr1
                    129: and/or
                    130: .Ar expr2
                    131: evaluate to true (logical
1.27      schwarze  132: .Sq or ) .
1.23      schwarze  133: .It Ar term
                    134: True if
                    135: .Ar term
                    136: is satisfied.
                    137: This has syntax
1.27      schwarze  138: .Sm off
                    139: .Oo
                    140: .Op Ar key Op , Ar key ...
                    141: .Pq Cm = | ~
                    142: .Oc
1.29    ! schwarze  143: .Ar val ,
        !           144: .Sm on
1.27      schwarze  145: where
                    146: .Ar key
1.4       kristaps  147: is an
                    148: .Xr mdoc 7
                    149: macro to query and
1.27      schwarze  150: .Ar val
1.4       kristaps  151: is its value.
1.10      kristaps  152: See
                    153: .Sx Macro Keys
                    154: for a list of available keys.
1.4       kristaps  155: Operator
1.27      schwarze  156: .Cm =
1.23      schwarze  157: evaluates a substring, while
1.27      schwarze  158: .Cm ~
1.23      schwarze  159: evaluates a regular expression.
                    160: .It Fl i Ar term
                    161: If
                    162: .Ar term
                    163: is a regular expression, it
                    164: is evaluated case-insensitively.
                    165: Has no effect on substring terms.
                    166: .El
                    167: .Pp
                    168: .Nm whatis
                    169: considers an
                    170: .Ar expression
                    171: to consist of an opaque keyword.
1.1       kristaps  172: .Pp
1.27      schwarze  173: Results are sorted by manual sections and names, with output formatted as
1.23      schwarze  174: .Pp
1.27      schwarze  175: .D1 name[, name...](sec) \- description
1.23      schwarze  176: .Pp
                    177: Where
1.27      schwarze  178: .Dq name
                    179: is the manual's name,
                    180: .Dq sec
1.3       kristaps  181: is the manual section, and
1.27      schwarze  182: .Dq description
1.1       kristaps  183: is the manual's short description.
                    184: If an architecture is specified for the manual, it is displayed as
1.23      schwarze  185: .Pp
1.27      schwarze  186: .D1 name(sec/arch) \- description
1.23      schwarze  187: .Pp
                    188: Resulting manuals may be accessed as
                    189: .Pp
1.27      schwarze  190: .Dl $ man \-s sec name
1.23      schwarze  191: .Pp
                    192: If an architecture is specified in the output, use
                    193: .Pp
1.27      schwarze  194: .Dl $ man \-s sec \-S arch name
1.10      kristaps  195: .Ss Macro Keys
1.23      schwarze  196: Queries evaluate over a subset of
1.10      kristaps  197: .Xr mdoc 7
                    198: macros indexed by
1.28      schwarze  199: .Xr makewhatis 8 .
1.10      kristaps  200: In addition to the macro keys listed below, the special key
                    201: .Cm any
                    202: may be used to match any available macro key.
                    203: .Pp
                    204: Names and description:
                    205: .Bl -column "xLix" description -offset indent -compact
                    206: .It Li \&Nm Ta manual name
                    207: .It Li \&Nd Ta one-line manual description
1.24      schwarze  208: .It Li arch Ta machine architecture (case-insensitive)
                    209: .It Li sec  Ta manual section number
1.10      kristaps  210: .El
                    211: .Pp
                    212: Sections and cross references:
                    213: .Bl -column "xLix" description -offset indent -compact
                    214: .It Li \&Sh Ta section header (excluding standard sections)
                    215: .It Li \&Ss Ta subsection header
                    216: .It Li \&Xr Ta cross reference to another manual page
                    217: .It Li \&Rs Ta bibliographic reference
                    218: .El
                    219: .Pp
                    220: Semantic markup for command line utilities:
                    221: .Bl -column "xLix" description -offset indent -compact
                    222: .It Li \&Fl Ta command line options (flags)
                    223: .It Li \&Cm Ta command modifier
                    224: .It Li \&Ar Ta command argument
                    225: .It Li \&Ic Ta internal or interactive command
                    226: .It Li \&Ev Ta environmental variable
                    227: .It Li \&Pa Ta file system path
                    228: .El
                    229: .Pp
                    230: Semantic markup for function libraries:
                    231: .Bl -column "xLix" description -offset indent -compact
                    232: .It Li \&Lb Ta function library name
                    233: .It Li \&In Ta include file
                    234: .It Li \&Ft Ta function return type
                    235: .It Li \&Fn Ta function name
                    236: .It Li \&Fa Ta function argument type and name
                    237: .It Li \&Vt Ta variable type
                    238: .It Li \&Va Ta variable name
                    239: .It Li \&Dv Ta defined variable or preprocessor constant
                    240: .It Li \&Er Ta error constant
                    241: .It Li \&Ev Ta environmental variable
                    242: .El
                    243: .Pp
                    244: Various semantic markup:
                    245: .Bl -column "xLix" description -offset indent -compact
                    246: .It Li \&An Ta author name
                    247: .It Li \&Lk Ta hyperlink
                    248: .It Li \&Mt Ta Do mailto Dc hyperlink
                    249: .It Li \&Cd Ta kernel configuration declaration
                    250: .It Li \&Ms Ta mathematical symbol
                    251: .It Li \&Tn Ta tradename
                    252: .El
                    253: .Pp
                    254: Physical markup:
                    255: .Bl -column "xLix" description -offset indent -compact
                    256: .It Li \&Em Ta italic font or underline
                    257: .It Li \&Sy Ta boldface font
                    258: .It Li \&Li Ta typewriter font
                    259: .El
                    260: .Pp
                    261: Text production:
                    262: .Bl -column "xLix" description -offset indent -compact
                    263: .It Li \&St Ta reference to a standards document
                    264: .It Li \&At Ta At No version reference
                    265: .It Li \&Bx Ta Bx No version reference
                    266: .It Li \&Bsx Ta Bsx No version reference
                    267: .It Li \&Nx Ta Nx No version reference
                    268: .It Li \&Fx Ta Fx No version reference
                    269: .It Li \&Ox Ta Ox No version reference
                    270: .It Li \&Dx Ta Dx No version reference
                    271: .El
1.6       kristaps  272: .Sh ENVIRONMENT
1.23      schwarze  273: .Bl -tag -width MANPATH
1.6       kristaps  274: .It Ev MANPATH
1.23      schwarze  275: The standard search path used by
                    276: .Xr man 1
                    277: may be changed by specifying a path in the
                    278: .Ev MANPATH
                    279: environment variable.
1.6       kristaps  280: Invalid paths, or paths without manual databases, are ignored.
1.9       schwarze  281: Overridden by
1.7       kristaps  282: .Fl M .
1.14      kristaps  283: If
                    284: .Ev MANPATH
1.23      schwarze  285: begins with a colon, it is appended to the default list;
                    286: if it ends with a colon, it is prepended to the default list;
                    287: or if it contains two adjacent colons,
                    288: the standard search path is inserted between the colons.
                    289: If none of these conditions are met, it overrides the
                    290: standard search path.
1.13      schwarze  291: .El
                    292: .Sh FILES
                    293: .Bl -tag -width "/etc/man.conf" -compact
1.22      schwarze  294: .It Pa mandoc.db
1.13      schwarze  295: name of the
1.28      schwarze  296: .Xr makewhatis 8
1.13      schwarze  297: keyword database
                    298: .It Pa /etc/man.conf
                    299: default
                    300: .Xr man 1
                    301: configuration file
1.6       kristaps  302: .El
1.1       kristaps  303: .Sh EXIT STATUS
                    304: .Ex -std
                    305: .Sh EXAMPLES
                    306: Search for
1.23      schwarze  307: .Qq .cf
                    308: as a substring of manual names and descriptions:
1.4       kristaps  309: .Pp
1.23      schwarze  310: .Dl $ apropos .cf
1.4       kristaps  311: .Pp
1.11      kristaps  312: Include matches for
1.23      schwarze  313: .Qq .cnf
1.11      kristaps  314: and
1.23      schwarze  315: .Qq .conf
                    316: as well:
                    317: .Pp
                    318: .Dl $ apropos .cf .cnf .conf
                    319: .Pp
                    320: Search in names and descriptions using a regular expression:
1.4       kristaps  321: .Pp
1.23      schwarze  322: .Dl $ apropos '~set.?[ug]id'
1.4       kristaps  323: .Pp
1.27      schwarze  324: Search for manuals in the library section mentioning both the
1.23      schwarze  325: .Qq optind
                    326: and the
1.4       kristaps  327: .Qq optarg
1.23      schwarze  328: variables:
                    329: .Pp
                    330: .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
1.1       kristaps  331: .Pp
1.23      schwarze  332: Do exactly the same as calling
                    333: .Xr whatis 1
                    334: with the argument
                    335: .Qq ssh :
                    336: .Pp
                    337: .Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]'
1.24      schwarze  338: .Pp
                    339: The following two invocations are equivalent:
                    340: .Pp
                    341: .D1 Li $ apropos -S Ar arch Li -s Ar section expression
                    342: .Bd -ragged -offset indent
                    343: .Li $ apropos \e( Ar expression Li \e)
                    344: .Li -a arch~^( Ns Ar arch Ns Li |any)$
                    345: .Li -a sec~^ Ns Ar section Ns Li $
                    346: .Ed
1.1       kristaps  347: .Sh SEE ALSO
1.23      schwarze  348: .Xr man 1 ,
                    349: .Xr re_format 7 ,
1.28      schwarze  350: .Xr makewhatis 8
1.23      schwarze  351: .Sh HISTORY
                    352: An
                    353: .Nm
                    354: utility first appeared in
                    355: .Bx 2 .
                    356: It was rewritten from scratch for
1.24      schwarze  357: .Ox 5.6 .
1.23      schwarze  358: .Pp
                    359: The
                    360: .Fl M
                    361: option and the
                    362: .Ev MANPATH
                    363: variable first appeared in
                    364: .Bx 4.3 ;
                    365: .Fl m
                    366: in
                    367: .Bx 4.3 Reno ;
                    368: .Fl C
                    369: in
                    370: .Bx 4.4 Lite1 ;
                    371: and
                    372: .Fl S
                    373: and
                    374: .Fl s
                    375: in
                    376: .Ox 4.5 .
1.1       kristaps  377: .Sh AUTHORS
1.23      schwarze  378: .An -nosplit
                    379: .An Bill Joy
                    380: wrote the original
                    381: .Bx
1.1       kristaps  382: .Nm
1.23      schwarze  383: in February 1979.
                    384: The current version was written by
1.24      schwarze  385: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
                    386: and
                    387: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .

CVSweb