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

Annotation of mandoc/apropos.1, Revision 1.17

1.17    ! kristaps    1: .\"    $Id: apropos.1,v 1.16 2011/12/25 19:35:44 kristaps 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.16      kristaps   17: .Dd $Mdocdate: December 25 2011 $
1.1       kristaps   18: .Dt APROPOS 1
                     19: .Os
                     20: .Sh NAME
                     21: .Nm apropos
1.5       kristaps   22: .Nd search manual page databases
1.1       kristaps   23: .Sh SYNOPSIS
                     24: .Nm
1.13      schwarze   25: .Op Fl C Ar file
1.7       kristaps   26: .Op Fl M Ar manpath
1.5       kristaps   27: .Op Fl m Ar manpath
1.3       kristaps   28: .Op Fl S Ar arch
                     29: .Op Fl s Ar section
1.13      schwarze   30: .Ar expression ...
1.1       kristaps   31: .Sh DESCRIPTION
                     32: The
                     33: .Nm
1.5       kristaps   34: utility queries manual page databases generated by
1.8       kristaps   35: .Xr mandocdb 8 ,
1.4       kristaps   36: evaluating on
                     37: .Ar expression
1.5       kristaps   38: for each file in each database.
1.16      kristaps   39: .Pp
                     40: By default,
                     41: .Nm
                     42: searches for
                     43: .Xr mandocdb 8
                     44: databases in the default paths stipulated by
                     45: .Xr man 1 ,
                     46: parses terms as case-sensitive regular expressions
1.17    ! kristaps   47: over manual names and descriptions.
1.16      kristaps   48: Multiple terms imply pairwise
                     49: .Fl o .
1.17    ! kristaps   50: If standard output is a TTY, a result may be selected from a list and
        !            51: its manual displayed with the pager.
1.16      kristaps   52: .Pp
1.1       kristaps   53: Its arguments are as follows:
                     54: .Bl -tag -width Ds
1.13      schwarze   55: .It Fl C Ar file
                     56: Specify an alternative configuration
                     57: .Ar file
                     58: in
                     59: .Xr man.conf 5
                     60: format.
1.7       kristaps   61: .It Fl M Ar manpath
                     62: Use the colon-separated path instead of the default list of paths
                     63: searched for
                     64: .Xr mandocdb 8
                     65: databases.
                     66: Invalid paths, or paths without manual databases, are ignored.
1.5       kristaps   67: .It Fl m Ar manpath
1.9       schwarze   68: Prepend the colon-separated paths to the list of paths searched
1.6       kristaps   69: for
1.5       kristaps   70: .Xr mandocdb 8
                     71: databases.
1.6       kristaps   72: Invalid paths, or paths without manual databases, are ignored.
1.3       kristaps   73: .It Fl S Ar arch
1.1       kristaps   74: Search only for a particular architecture.
1.3       kristaps   75: .It Fl s Ar cat
                     76: Search only for a manual section.
1.1       kristaps   77: See
                     78: .Xr man 1
1.3       kristaps   79: for a listing of manual sections.
1.4       kristaps   80: .El
                     81: .Pp
                     82: An
                     83: .Ar expression
                     84: consists of search terms joined by logical operators
                     85: .Fl a
                     86: .Pq and
                     87: and
                     88: .Fl o
                     89: .Pq or .
                     90: The
                     91: .Fl a
                     92: operator has precedence over
                     93: .Fl o
                     94: and both are evaluated left-to-right.
                     95: .Bl -tag -width Ds
                     96: .It \&( Ar expr No \&)
                     97: True if the subexpression
                     98: .Ar expr
                     99: is true.
                    100: .It Ar expr1 Fl a Ar expr2
                    101: True if both
                    102: .Ar expr1
                    103: and
                    104: .Ar expr2
                    105: are true (logical
                    106: .Qq and ) .
                    107: .It Ar expr1 Oo Fl o Oc Ar expr2
                    108: True if
                    109: .Ar expr1
                    110: and/or
                    111: .Ar expr2
                    112: evaluate to true (logical
                    113: .Qq or ) .
                    114: .It Ar term
                    115: True if
                    116: .Ar term
                    117: is satisfied.
                    118: This has syntax
                    119: .Li [key[,key]*(=~)]?val ,
                    120: where operand
1.10      kristaps  121: .Cm key
1.4       kristaps  122: is an
                    123: .Xr mdoc 7
                    124: macro to query and
1.10      kristaps  125: .Cm val
1.4       kristaps  126: is its value.
1.10      kristaps  127: See
                    128: .Sx Macro Keys
                    129: for a list of available keys.
1.4       kristaps  130: Operator
                    131: .Li \&=
                    132: evaluates a substring, while
                    133: .Li \&~
                    134: evaluates a regular expression.
                    135: .It Fl i Ar term
1.11      kristaps  136: If
1.4       kristaps  137: .Ar term
1.11      kristaps  138: is a regular expression, it
1.4       kristaps  139: is evaluated case-insensitively.
1.11      kristaps  140: Has no effect on substring terms.
1.1       kristaps  141: .El
                    142: .Pp
1.4       kristaps  143: Results are sorted by manual title, with output formatted as
1.1       kristaps  144: .Pp
1.3       kristaps  145: .D1 title(sec) \- description
1.1       kristaps  146: .Pp
                    147: Where
                    148: .Qq title
                    149: is the manual's title (note multiple manual names may exist for one
                    150: title),
1.3       kristaps  151: .Qq sec
                    152: is the manual section, and
1.1       kristaps  153: .Qq description
                    154: is the manual's short description.
                    155: If an architecture is specified for the manual, it is displayed as
                    156: .Pp
                    157: .D1 title(cat/arch) \- description
                    158: .Pp
1.17    ! kristaps  159: If on a TTY, results are prefixed with a numeric identifier.
1.1       kristaps  160: .Pp
1.17    ! kristaps  161: .D1 [index] title(cat) \- description
1.1       kristaps  162: .Pp
1.17    ! kristaps  163: One may choose a manual be entering the index at the prompt.
        !           164: Valid choices are displayed using
        !           165: .Ev MANPAGER ,
        !           166: or failing that ,
        !           167: .Ev PAGER
        !           168: or just
        !           169: .Xr more 1 .
        !           170: Source pages are formatted with
        !           171: .Xr mandoc 1 ;
        !           172: preformatted pages with
        !           173: .Xr cat 1 .
1.10      kristaps  174: .Ss Macro Keys
                    175: Queries evaluate over a subset of
                    176: .Xr mdoc 7
                    177: macros indexed by
                    178: .Xr mandocdb 8 .
                    179: In addition to the macro keys listed below, the special key
                    180: .Cm any
                    181: may be used to match any available macro key.
                    182: .Pp
                    183: Names and description:
                    184: .Bl -column "xLix" description -offset indent -compact
                    185: .It Li \&Nm Ta manual name
                    186: .It Li \&Nd Ta one-line manual description
                    187: .El
                    188: .Pp
                    189: Sections and cross references:
                    190: .Bl -column "xLix" description -offset indent -compact
                    191: .It Li \&Sh Ta section header (excluding standard sections)
                    192: .It Li \&Ss Ta subsection header
                    193: .It Li \&Xr Ta cross reference to another manual page
                    194: .It Li \&Rs Ta bibliographic reference
                    195: .El
                    196: .Pp
                    197: Semantic markup for command line utilities:
                    198: .Bl -column "xLix" description -offset indent -compact
                    199: .It Li \&Fl Ta command line options (flags)
                    200: .It Li \&Cm Ta command modifier
                    201: .It Li \&Ar Ta command argument
                    202: .It Li \&Ic Ta internal or interactive command
                    203: .It Li \&Ev Ta environmental variable
                    204: .It Li \&Pa Ta file system path
                    205: .El
                    206: .Pp
                    207: Semantic markup for function libraries:
                    208: .Bl -column "xLix" description -offset indent -compact
                    209: .It Li \&Lb Ta function library name
                    210: .It Li \&In Ta include file
                    211: .It Li \&Ft Ta function return type
                    212: .It Li \&Fn Ta function name
                    213: .It Li \&Fa Ta function argument type and name
                    214: .It Li \&Vt Ta variable type
                    215: .It Li \&Va Ta variable name
                    216: .It Li \&Dv Ta defined variable or preprocessor constant
                    217: .It Li \&Er Ta error constant
                    218: .It Li \&Ev Ta environmental variable
                    219: .El
                    220: .Pp
                    221: Various semantic markup:
                    222: .Bl -column "xLix" description -offset indent -compact
                    223: .It Li \&An Ta author name
                    224: .It Li \&Lk Ta hyperlink
                    225: .It Li \&Mt Ta Do mailto Dc hyperlink
                    226: .It Li \&Cd Ta kernel configuration declaration
                    227: .It Li \&Ms Ta mathematical symbol
                    228: .It Li \&Tn Ta tradename
                    229: .El
                    230: .Pp
                    231: Physical markup:
                    232: .Bl -column "xLix" description -offset indent -compact
                    233: .It Li \&Em Ta italic font or underline
                    234: .It Li \&Sy Ta boldface font
                    235: .It Li \&Li Ta typewriter font
                    236: .El
                    237: .Pp
                    238: Text production:
                    239: .Bl -column "xLix" description -offset indent -compact
                    240: .It Li \&St Ta reference to a standards document
                    241: .It Li \&At Ta At No version reference
                    242: .It Li \&Bx Ta Bx No version reference
                    243: .It Li \&Bsx Ta Bsx No version reference
                    244: .It Li \&Nx Ta Nx No version reference
                    245: .It Li \&Fx Ta Fx No version reference
                    246: .It Li \&Ox Ta Ox No version reference
                    247: .It Li \&Dx Ta Dx No version reference
                    248: .El
1.6       kristaps  249: .Sh ENVIRONMENT
                    250: .Bl -tag -width Ds
1.17    ! kristaps  251: .It Ev MANPAGER
        !           252: Default pager for manuals.
        !           253: If this is unset, falls back to
        !           254: .Ev Pager .
        !           255: .It Ev PAGER
        !           256: The second choice for a manual pager.
        !           257: If this is unset, use
        !           258: .Xr more 1 .
1.6       kristaps  259: .It Ev MANPATH
1.14      kristaps  260: Colon-separated paths modifying the default list of paths searched for
1.6       kristaps  261: manual databases.
                    262: Invalid paths, or paths without manual databases, are ignored.
1.9       schwarze  263: Overridden by
1.7       kristaps  264: .Fl M .
1.14      kristaps  265: If
                    266: .Ev MANPATH
                    267: begins with a
                    268: .Sq \&: ,
                    269: it is appended to the default list;
                    270: else if it ends with
                    271: .Sq \&: ,
                    272: it is prepended to the default list; else if it contains
                    273: .Sq \&:: ,
                    274: the default list is inserted between the colons.
                    275: If none of these conditions are met, it overrides the default list.
1.13      schwarze  276: .El
                    277: .Sh FILES
                    278: .Bl -tag -width "/etc/man.conf" -compact
1.15      schwarze  279: .It Pa whatis.db
1.13      schwarze  280: name of the
                    281: .Xr mandocdb 8
                    282: keyword database
1.15      schwarze  283: .It Pa whatis.index
1.13      schwarze  284: name of the
                    285: .Xr mandocdb 8
                    286: filename database
                    287: .It Pa /etc/man.conf
                    288: default
                    289: .Xr man 1
                    290: configuration file
1.6       kristaps  291: .El
1.1       kristaps  292: .Sh EXIT STATUS
                    293: .Ex -std
                    294: .Sh EXAMPLES
                    295: Search for
1.4       kristaps  296: .Qq mdoc
1.12      kristaps  297: as a substring and regular expression
1.11      kristaps  298: within each manual name and description:
1.4       kristaps  299: .Pp
                    300: .Dl $ apropos mdoc
1.11      kristaps  301: .Dl $ apropos ~^mdoc$
1.4       kristaps  302: .Pp
1.11      kristaps  303: Include matches for
                    304: .Qq roff
                    305: and
1.4       kristaps  306: .Qq man
1.11      kristaps  307: for the regular expression case:
1.4       kristaps  308: .Pp
1.11      kristaps  309: .Dl $ apropos ~^mdoc$ roff man
                    310: .Dl $ apropos ~^mdoc$ \-o roff \-o man
1.4       kristaps  311: .Pp
                    312: Search for
1.1       kristaps  313: .Qq optind
1.4       kristaps  314: and
                    315: .Qq optarg
                    316: as variable names in the library category:
1.1       kristaps  317: .Pp
1.11      kristaps  318: .Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$
1.1       kristaps  319: .Sh SEE ALSO
1.17    ! kristaps  320: .Xr more 1
1.11      kristaps  321: .Xr re_format 7 ,
                    322: .Xr mandocdb 8
1.1       kristaps  323: .Sh AUTHORS
                    324: The
                    325: .Nm
                    326: utility was written by
1.2       kristaps  327: .An Kristaps Dzonsons ,
                    328: .Mt kristaps@bsd.lv .

CVSweb