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

Annotation of mandoc/apropos.1, Revision 1.24

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

CVSweb