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

Annotation of mandoc/apropos.1, Revision 1.16.2.3

1.16.2.3! schwarze    1: .\"    $Id: apropos.1,v 1.16.2.2 2013/09/17 20:42:09 schwarze Exp $
1.1       kristaps    2: .\"
                      3: .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
                      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.2.3! schwarze   17: .Dd $Mdocdate: September 17 2013 $
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.16.2.1  schwarze   26: .Op Fl M Ar path
                     27: .Op Fl m Ar path
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
                     47: .Pq the Li \&~ operator
                     48: over manual names and descriptions
                     49: .Pq the Li \&Nm No and Li \&Nd No macro keys .
                     50: Multiple terms imply pairwise
                     51: .Fl o .
                     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.16.2.1  schwarze   61: .It Fl M Ar path
1.7       kristaps   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.16.2.1  schwarze   67: .It Fl m Ar path
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
                    159: Resulting manuals may be accessed as
                    160: .Pp
1.3       kristaps  161: .Dl $ man \-s sec title
1.1       kristaps  162: .Pp
                    163: If an architecture is specified in the output, use
                    164: .Pp
1.3       kristaps  165: .Dl $ man \-s sec \-S arch title
1.10      kristaps  166: .Ss Macro Keys
                    167: Queries evaluate over a subset of
                    168: .Xr mdoc 7
                    169: macros indexed by
                    170: .Xr mandocdb 8 .
                    171: In addition to the macro keys listed below, the special key
                    172: .Cm any
                    173: may be used to match any available macro key.
                    174: .Pp
                    175: Names and description:
                    176: .Bl -column "xLix" description -offset indent -compact
                    177: .It Li \&Nm Ta manual name
                    178: .It Li \&Nd Ta one-line manual description
                    179: .El
                    180: .Pp
                    181: Sections and cross references:
                    182: .Bl -column "xLix" description -offset indent -compact
                    183: .It Li \&Sh Ta section header (excluding standard sections)
                    184: .It Li \&Ss Ta subsection header
                    185: .It Li \&Xr Ta cross reference to another manual page
                    186: .It Li \&Rs Ta bibliographic reference
                    187: .El
                    188: .Pp
                    189: Semantic markup for command line utilities:
                    190: .Bl -column "xLix" description -offset indent -compact
                    191: .It Li \&Fl Ta command line options (flags)
                    192: .It Li \&Cm Ta command modifier
                    193: .It Li \&Ar Ta command argument
                    194: .It Li \&Ic Ta internal or interactive command
                    195: .It Li \&Ev Ta environmental variable
                    196: .It Li \&Pa Ta file system path
                    197: .El
                    198: .Pp
                    199: Semantic markup for function libraries:
                    200: .Bl -column "xLix" description -offset indent -compact
                    201: .It Li \&Lb Ta function library name
                    202: .It Li \&In Ta include file
                    203: .It Li \&Ft Ta function return type
                    204: .It Li \&Fn Ta function name
                    205: .It Li \&Fa Ta function argument type and name
                    206: .It Li \&Vt Ta variable type
                    207: .It Li \&Va Ta variable name
                    208: .It Li \&Dv Ta defined variable or preprocessor constant
                    209: .It Li \&Er Ta error constant
                    210: .It Li \&Ev Ta environmental variable
                    211: .El
                    212: .Pp
                    213: Various semantic markup:
                    214: .Bl -column "xLix" description -offset indent -compact
                    215: .It Li \&An Ta author name
                    216: .It Li \&Lk Ta hyperlink
                    217: .It Li \&Mt Ta Do mailto Dc hyperlink
                    218: .It Li \&Cd Ta kernel configuration declaration
                    219: .It Li \&Ms Ta mathematical symbol
                    220: .It Li \&Tn Ta tradename
                    221: .El
                    222: .Pp
                    223: Physical markup:
                    224: .Bl -column "xLix" description -offset indent -compact
                    225: .It Li \&Em Ta italic font or underline
                    226: .It Li \&Sy Ta boldface font
                    227: .It Li \&Li Ta typewriter font
                    228: .El
                    229: .Pp
                    230: Text production:
                    231: .Bl -column "xLix" description -offset indent -compact
                    232: .It Li \&St Ta reference to a standards document
                    233: .It Li \&At Ta At No version reference
                    234: .It Li \&Bx Ta Bx No version reference
                    235: .It Li \&Bsx Ta Bsx No version reference
                    236: .It Li \&Nx Ta Nx No version reference
                    237: .It Li \&Fx Ta Fx No version reference
                    238: .It Li \&Ox Ta Ox No version reference
                    239: .It Li \&Dx Ta Dx No version reference
                    240: .El
1.6       kristaps  241: .Sh ENVIRONMENT
                    242: .Bl -tag -width Ds
                    243: .It Ev MANPATH
1.14      kristaps  244: Colon-separated paths modifying the default list of paths searched for
1.6       kristaps  245: manual databases.
                    246: Invalid paths, or paths without manual databases, are ignored.
1.9       schwarze  247: Overridden by
1.7       kristaps  248: .Fl M .
1.14      kristaps  249: If
                    250: .Ev MANPATH
                    251: begins with a
                    252: .Sq \&: ,
                    253: it is appended to the default list;
                    254: else if it ends with
                    255: .Sq \&: ,
                    256: it is prepended to the default list; else if it contains
                    257: .Sq \&:: ,
                    258: the default list is inserted between the colons.
                    259: If none of these conditions are met, it overrides the default list.
1.13      schwarze  260: .El
                    261: .Sh FILES
                    262: .Bl -tag -width "/etc/man.conf" -compact
1.16.2.3! schwarze  263: .It Pa mandoc.db
1.13      schwarze  264: name of the
                    265: .Xr mandocdb 8
                    266: keyword database
1.16.2.3! schwarze  267: .It Pa mandoc.index
1.13      schwarze  268: name of the
                    269: .Xr mandocdb 8
                    270: filename database
                    271: .It Pa /etc/man.conf
                    272: default
                    273: .Xr man 1
                    274: configuration file
1.6       kristaps  275: .El
1.1       kristaps  276: .Sh EXIT STATUS
                    277: .Ex -std
                    278: .Sh EXAMPLES
                    279: Search for
1.4       kristaps  280: .Qq mdoc
1.12      kristaps  281: as a substring and regular expression
1.11      kristaps  282: within each manual name and description:
1.4       kristaps  283: .Pp
                    284: .Dl $ apropos mdoc
1.11      kristaps  285: .Dl $ apropos ~^mdoc$
1.4       kristaps  286: .Pp
1.11      kristaps  287: Include matches for
                    288: .Qq roff
                    289: and
1.4       kristaps  290: .Qq man
1.11      kristaps  291: for the regular expression case:
1.4       kristaps  292: .Pp
1.11      kristaps  293: .Dl $ apropos ~^mdoc$ roff man
                    294: .Dl $ apropos ~^mdoc$ \-o roff \-o man
1.4       kristaps  295: .Pp
                    296: Search for
1.1       kristaps  297: .Qq optind
1.4       kristaps  298: and
                    299: .Qq optarg
                    300: as variable names in the library category:
1.1       kristaps  301: .Pp
1.11      kristaps  302: .Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$
1.1       kristaps  303: .Sh SEE ALSO
                    304: .Xr man 1 ,
1.11      kristaps  305: .Xr re_format 7 ,
                    306: .Xr mandocdb 8
1.1       kristaps  307: .Sh AUTHORS
                    308: The
                    309: .Nm
                    310: utility was written by
1.16.2.2  schwarze  311: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .

CVSweb