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

Annotation of mandoc/apropos.1, Revision 1.41

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

CVSweb