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

Annotation of mandoc/apropos.1, Revision 1.31

1.31    ! schwarze    1: .\"    $Id: apropos.1,v 1.30 2014/08/21 01:52:59 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.31    ! schwarze   18: .Dd $Mdocdate: August 21 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.31    ! schwarze   27: .Op Fl afkw
1.13      schwarze   28: .Op Fl C Ar file
1.20      schwarze   29: .Op Fl M Ar path
                     30: .Op Fl m Ar path
1.24      schwarze   31: .Op Fl O Ar outkey
1.3       kristaps   32: .Op Fl S Ar arch
                     33: .Op Fl s Ar section
1.13      schwarze   34: .Ar expression ...
1.1       kristaps   35: .Sh DESCRIPTION
                     36: The
1.19      kristaps   37: .Nm apropos
                     38: and
                     39: .Nm whatis
                     40: utilities query manual page databases generated by
1.28      schwarze   41: .Xr makewhatis 8 ,
1.27      schwarze   42: evaluating
1.4       kristaps   43: .Ar expression
1.5       kristaps   44: for each file in each database.
1.30      schwarze   45: By default, they display the names, section numbers, and description lines
1.27      schwarze   46: of all matching manuals.
1.16      kristaps   47: .Pp
                     48: By default,
                     49: .Nm
                     50: searches for
1.28      schwarze   51: .Xr makewhatis 8
1.16      kristaps   52: databases in the default paths stipulated by
1.27      schwarze   53: .Xr man 1
                     54: and uses case-insensitive substring matching
                     55: .Pq the Cm = No operator
1.23      schwarze   56: over manual names and descriptions
                     57: .Pq the Li \&Nm No and Li \&Nd No macro keys .
                     58: Multiple terms imply pairwise
                     59: .Fl o .
1.31    ! schwarze   60: .Pp
1.19      kristaps   61: .Nm whatis
1.31    ! schwarze   62: is a synonym for
        !            63: .Nm
        !            64: .Fl f .
1.16      kristaps   65: .Pp
1.31    ! schwarze   66: The options are as follows:
1.1       kristaps   67: .Bl -tag -width Ds
1.31    ! schwarze   68: .It Fl a
        !            69: Instead of showing only the title lines, show the complete manual pages,
        !            70: just like
        !            71: .Xr man 1
        !            72: .Fl a
        !            73: would.
        !            74: In this mode, the options
        !            75: .Fl IOTW
        !            76: described in the
        !            77: .Xr mandoc 1
        !            78: manual are also available.
1.13      schwarze   79: .It Fl C Ar file
                     80: Specify an alternative configuration
                     81: .Ar file
                     82: in
                     83: .Xr man.conf 5
                     84: format.
1.31    ! schwarze   85: .It Fl f
        !            86: Search for all words in
        !            87: .Ar expression
        !            88: in manual page names only.
        !            89: The search is case insensitive and matches whole words only.
        !            90: In this mode, macro keys, comparison operators, and logical operators
        !            91: are not available.
        !            92: This overrides any earlier
        !            93: .Fl k
        !            94: option.
        !            95: .It Fl k
        !            96: Support the full
        !            97: .Ar expression
        !            98: syntax.
        !            99: This overrides any earlier
        !           100: .Fl f
        !           101: option.
        !           102: It is the default for
        !           103: .Nm .
1.20      schwarze  104: .It Fl M Ar path
1.7       kristaps  105: Use the colon-separated path instead of the default list of paths
                    106: searched for
1.28      schwarze  107: .Xr makewhatis 8
1.7       kristaps  108: databases.
                    109: Invalid paths, or paths without manual databases, are ignored.
1.20      schwarze  110: .It Fl m Ar path
1.9       schwarze  111: Prepend the colon-separated paths to the list of paths searched
1.6       kristaps  112: for
1.28      schwarze  113: .Xr makewhatis 8
1.5       kristaps  114: databases.
1.6       kristaps  115: Invalid paths, or paths without manual databases, are ignored.
1.24      schwarze  116: .It Fl O Ar outkey
                    117: Show the values associated with the key
                    118: .Ar outkey
                    119: instead of the manual descriptions.
1.3       kristaps  120: .It Fl S Ar arch
1.23      schwarze  121: Restrict the search to pages for the specified
                    122: .Xr machine 1
                    123: architecture.
                    124: .Ar arch
                    125: is case insensitive.
                    126: By default, pages for all architectures are shown.
                    127: .It Fl s Ar section
                    128: Restrict the search to the specified section of the manual.
                    129: By default, pages from all sections are shown.
1.1       kristaps  130: See
                    131: .Xr man 1
1.23      schwarze  132: for a listing of sections.
1.31    ! schwarze  133: .It Fl w
        !           134: Instead of showing title lines, show the pathnames of the matching
        !           135: manual pages, just like
        !           136: .Xr man 1
        !           137: .Fl w
        !           138: would.
1.4       kristaps  139: .El
                    140: .Pp
1.23      schwarze  141: An
1.4       kristaps  142: .Ar expression
1.23      schwarze  143: consists of search terms joined by logical operators
                    144: .Fl a
                    145: .Pq and
                    146: and
                    147: .Fl o
                    148: .Pq or .
                    149: The
                    150: .Fl a
                    151: operator has precedence over
                    152: .Fl o
                    153: and both are evaluated left-to-right.
                    154: .Bl -tag -width Ds
                    155: .It \&( Ar expr No \&)
                    156: True if the subexpression
                    157: .Ar expr
                    158: is true.
                    159: .It Ar expr1 Fl a Ar expr2
                    160: True if both
                    161: .Ar expr1
                    162: and
                    163: .Ar expr2
                    164: are true (logical
1.27      schwarze  165: .Sq and ) .
1.23      schwarze  166: .It Ar expr1 Oo Fl o Oc Ar expr2
                    167: True if
                    168: .Ar expr1
                    169: and/or
                    170: .Ar expr2
                    171: evaluate to true (logical
1.27      schwarze  172: .Sq or ) .
1.23      schwarze  173: .It Ar term
                    174: True if
                    175: .Ar term
                    176: is satisfied.
                    177: This has syntax
1.27      schwarze  178: .Sm off
                    179: .Oo
                    180: .Op Ar key Op , Ar key ...
                    181: .Pq Cm = | ~
                    182: .Oc
1.29      schwarze  183: .Ar val ,
                    184: .Sm on
1.27      schwarze  185: where
                    186: .Ar key
1.4       kristaps  187: is an
                    188: .Xr mdoc 7
                    189: macro to query and
1.27      schwarze  190: .Ar val
1.4       kristaps  191: is its value.
1.10      kristaps  192: See
                    193: .Sx Macro Keys
                    194: for a list of available keys.
1.4       kristaps  195: Operator
1.27      schwarze  196: .Cm =
1.23      schwarze  197: evaluates a substring, while
1.27      schwarze  198: .Cm ~
1.23      schwarze  199: evaluates a regular expression.
                    200: .It Fl i Ar term
                    201: If
                    202: .Ar term
                    203: is a regular expression, it
                    204: is evaluated case-insensitively.
                    205: Has no effect on substring terms.
                    206: .El
1.1       kristaps  207: .Pp
1.27      schwarze  208: Results are sorted by manual sections and names, with output formatted as
1.23      schwarze  209: .Pp
1.27      schwarze  210: .D1 name[, name...](sec) \- description
1.23      schwarze  211: .Pp
                    212: Where
1.27      schwarze  213: .Dq name
                    214: is the manual's name,
                    215: .Dq sec
1.3       kristaps  216: is the manual section, and
1.27      schwarze  217: .Dq description
1.1       kristaps  218: is the manual's short description.
                    219: If an architecture is specified for the manual, it is displayed as
1.23      schwarze  220: .Pp
1.27      schwarze  221: .D1 name(sec/arch) \- description
1.23      schwarze  222: .Pp
                    223: Resulting manuals may be accessed as
                    224: .Pp
1.27      schwarze  225: .Dl $ man \-s sec name
1.23      schwarze  226: .Pp
                    227: If an architecture is specified in the output, use
                    228: .Pp
1.27      schwarze  229: .Dl $ man \-s sec \-S arch name
1.10      kristaps  230: .Ss Macro Keys
1.23      schwarze  231: Queries evaluate over a subset of
1.10      kristaps  232: .Xr mdoc 7
                    233: macros indexed by
1.28      schwarze  234: .Xr makewhatis 8 .
1.10      kristaps  235: In addition to the macro keys listed below, the special key
                    236: .Cm any
                    237: may be used to match any available macro key.
                    238: .Pp
                    239: Names and description:
                    240: .Bl -column "xLix" description -offset indent -compact
                    241: .It Li \&Nm Ta manual name
                    242: .It Li \&Nd Ta one-line manual description
1.24      schwarze  243: .It Li arch Ta machine architecture (case-insensitive)
                    244: .It Li sec  Ta manual section number
1.10      kristaps  245: .El
                    246: .Pp
                    247: Sections and cross references:
                    248: .Bl -column "xLix" description -offset indent -compact
                    249: .It Li \&Sh Ta section header (excluding standard sections)
                    250: .It Li \&Ss Ta subsection header
                    251: .It Li \&Xr Ta cross reference to another manual page
                    252: .It Li \&Rs Ta bibliographic reference
                    253: .El
                    254: .Pp
                    255: Semantic markup for command line utilities:
                    256: .Bl -column "xLix" description -offset indent -compact
                    257: .It Li \&Fl Ta command line options (flags)
                    258: .It Li \&Cm Ta command modifier
                    259: .It Li \&Ar Ta command argument
                    260: .It Li \&Ic Ta internal or interactive command
                    261: .It Li \&Ev Ta environmental variable
                    262: .It Li \&Pa Ta file system path
                    263: .El
                    264: .Pp
                    265: Semantic markup for function libraries:
                    266: .Bl -column "xLix" description -offset indent -compact
                    267: .It Li \&Lb Ta function library name
                    268: .It Li \&In Ta include file
                    269: .It Li \&Ft Ta function return type
                    270: .It Li \&Fn Ta function name
                    271: .It Li \&Fa Ta function argument type and name
                    272: .It Li \&Vt Ta variable type
                    273: .It Li \&Va Ta variable name
                    274: .It Li \&Dv Ta defined variable or preprocessor constant
                    275: .It Li \&Er Ta error constant
                    276: .It Li \&Ev Ta environmental variable
                    277: .El
                    278: .Pp
                    279: Various semantic markup:
                    280: .Bl -column "xLix" description -offset indent -compact
                    281: .It Li \&An Ta author name
                    282: .It Li \&Lk Ta hyperlink
                    283: .It Li \&Mt Ta Do mailto Dc hyperlink
                    284: .It Li \&Cd Ta kernel configuration declaration
                    285: .It Li \&Ms Ta mathematical symbol
                    286: .It Li \&Tn Ta tradename
                    287: .El
                    288: .Pp
                    289: Physical markup:
                    290: .Bl -column "xLix" description -offset indent -compact
                    291: .It Li \&Em Ta italic font or underline
                    292: .It Li \&Sy Ta boldface font
                    293: .It Li \&Li Ta typewriter font
                    294: .El
                    295: .Pp
                    296: Text production:
                    297: .Bl -column "xLix" description -offset indent -compact
                    298: .It Li \&St Ta reference to a standards document
                    299: .It Li \&At Ta At No version reference
                    300: .It Li \&Bx Ta Bx No version reference
                    301: .It Li \&Bsx Ta Bsx No version reference
                    302: .It Li \&Nx Ta Nx No version reference
                    303: .It Li \&Fx Ta Fx No version reference
                    304: .It Li \&Ox Ta Ox No version reference
                    305: .It Li \&Dx Ta Dx No version reference
                    306: .El
1.6       kristaps  307: .Sh ENVIRONMENT
1.23      schwarze  308: .Bl -tag -width MANPATH
1.6       kristaps  309: .It Ev MANPATH
1.23      schwarze  310: The standard search path used by
                    311: .Xr man 1
                    312: may be changed by specifying a path in the
                    313: .Ev MANPATH
                    314: environment variable.
1.6       kristaps  315: Invalid paths, or paths without manual databases, are ignored.
1.9       schwarze  316: Overridden by
1.7       kristaps  317: .Fl M .
1.14      kristaps  318: If
                    319: .Ev MANPATH
1.23      schwarze  320: begins with a colon, it is appended to the default list;
                    321: if it ends with a colon, it is prepended to the default list;
                    322: or if it contains two adjacent colons,
                    323: the standard search path is inserted between the colons.
                    324: If none of these conditions are met, it overrides the
                    325: standard search path.
1.13      schwarze  326: .El
                    327: .Sh FILES
                    328: .Bl -tag -width "/etc/man.conf" -compact
1.22      schwarze  329: .It Pa mandoc.db
1.13      schwarze  330: name of the
1.28      schwarze  331: .Xr makewhatis 8
1.13      schwarze  332: keyword database
                    333: .It Pa /etc/man.conf
                    334: default
                    335: .Xr man 1
                    336: configuration file
1.6       kristaps  337: .El
1.1       kristaps  338: .Sh EXIT STATUS
                    339: .Ex -std
                    340: .Sh EXAMPLES
                    341: Search for
1.23      schwarze  342: .Qq .cf
                    343: as a substring of manual names and descriptions:
1.4       kristaps  344: .Pp
1.23      schwarze  345: .Dl $ apropos .cf
1.4       kristaps  346: .Pp
1.11      kristaps  347: Include matches for
1.23      schwarze  348: .Qq .cnf
1.11      kristaps  349: and
1.23      schwarze  350: .Qq .conf
                    351: as well:
                    352: .Pp
                    353: .Dl $ apropos .cf .cnf .conf
                    354: .Pp
                    355: Search in names and descriptions using a regular expression:
1.4       kristaps  356: .Pp
1.23      schwarze  357: .Dl $ apropos '~set.?[ug]id'
1.4       kristaps  358: .Pp
1.27      schwarze  359: Search for manuals in the library section mentioning both the
1.23      schwarze  360: .Qq optind
                    361: and the
1.4       kristaps  362: .Qq optarg
1.23      schwarze  363: variables:
                    364: .Pp
                    365: .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
1.1       kristaps  366: .Pp
1.23      schwarze  367: Do exactly the same as calling
                    368: .Xr whatis 1
                    369: with the argument
                    370: .Qq ssh :
                    371: .Pp
                    372: .Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]'
1.24      schwarze  373: .Pp
                    374: The following two invocations are equivalent:
                    375: .Pp
                    376: .D1 Li $ apropos -S Ar arch Li -s Ar section expression
                    377: .Bd -ragged -offset indent
                    378: .Li $ apropos \e( Ar expression Li \e)
                    379: .Li -a arch~^( Ns Ar arch Ns Li |any)$
                    380: .Li -a sec~^ Ns Ar section Ns Li $
                    381: .Ed
1.1       kristaps  382: .Sh SEE ALSO
1.23      schwarze  383: .Xr man 1 ,
                    384: .Xr re_format 7 ,
1.28      schwarze  385: .Xr makewhatis 8
1.23      schwarze  386: .Sh HISTORY
1.30      schwarze  387: Part of the functionality of
                    388: .Nm whatis
                    389: was already provided by the former
                    390: .Nm manwhere
                    391: utility in
                    392: .Bx 1 .
                    393: The
1.23      schwarze  394: .Nm
1.30      schwarze  395: and
                    396: .Nm whatis
                    397: utilities first appeared in
1.23      schwarze  398: .Bx 2 .
1.30      schwarze  399: They were rewritten from scratch for
1.24      schwarze  400: .Ox 5.6 .
1.23      schwarze  401: .Pp
                    402: The
                    403: .Fl M
                    404: option and the
                    405: .Ev MANPATH
                    406: variable first appeared in
                    407: .Bx 4.3 ;
                    408: .Fl m
                    409: in
                    410: .Bx 4.3 Reno ;
                    411: .Fl C
                    412: in
                    413: .Bx 4.4 Lite1 ;
                    414: and
                    415: .Fl S
                    416: and
                    417: .Fl s
                    418: in
1.30      schwarze  419: .Ox 4.5
                    420: for
                    421: .Nm
                    422: and in
                    423: .Ox 5.6
                    424: for
                    425: .Nm whatis .
1.1       kristaps  426: .Sh AUTHORS
1.23      schwarze  427: .An -nosplit
                    428: .An Bill Joy
1.30      schwarze  429: wrote
                    430: .Nm manwhere
                    431: in 1977 and the original
1.23      schwarze  432: .Bx
1.1       kristaps  433: .Nm
1.30      schwarze  434: and
                    435: .Nm whatis
1.23      schwarze  436: in February 1979.
                    437: The current version was written by
1.24      schwarze  438: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
                    439: and
                    440: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .

CVSweb