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

Annotation of mandoc/apropos.1, Revision 1.20

1.20    ! schwarze    1: .\"    $Id: apropos.1,v 1.19 2012/06/09 14:11:15 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.20    ! schwarze   17: .Dd $Mdocdate: June 9 2012 $
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.3       kristaps   29: .Op Fl S Ar arch
                     30: .Op Fl s Ar section
1.13      schwarze   31: .Ar expression ...
1.1       kristaps   32: .Sh DESCRIPTION
                     33: The
1.19      kristaps   34: .Nm apropos
                     35: and
                     36: .Nm whatis
                     37: utilities query manual page databases generated by
1.8       kristaps   38: .Xr mandocdb 8 ,
1.4       kristaps   39: evaluating on
                     40: .Ar expression
1.5       kristaps   41: for each file in each database.
1.16      kristaps   42: .Pp
                     43: By default,
                     44: .Nm
                     45: searches for
                     46: .Xr mandocdb 8
                     47: databases in the default paths stipulated by
1.18      kristaps   48: .Xr man 1
                     49: and
1.19      kristaps   50: maps terms to case-sensitive manual names and descriptions.
1.18      kristaps   51: Multiple terms are OR'd.
1.19      kristaps   52: .Nm whatis
                     53: maps terms only to case-sensitive manual names.
1.16      kristaps   54: .Pp
1.1       kristaps   55: Its arguments are as follows:
                     56: .Bl -tag -width Ds
1.13      schwarze   57: .It Fl C Ar file
                     58: Specify an alternative configuration
                     59: .Ar file
                     60: in
                     61: .Xr man.conf 5
                     62: format.
1.20    ! schwarze   63: .It Fl M Ar path
1.7       kristaps   64: Use the colon-separated path instead of the default list of paths
                     65: searched for
                     66: .Xr mandocdb 8
                     67: databases.
                     68: Invalid paths, or paths without manual databases, are ignored.
1.20    ! schwarze   69: .It Fl m Ar path
1.9       schwarze   70: Prepend the colon-separated paths to the list of paths searched
1.6       kristaps   71: for
1.5       kristaps   72: .Xr mandocdb 8
                     73: databases.
1.6       kristaps   74: Invalid paths, or paths without manual databases, are ignored.
1.3       kristaps   75: .It Fl S Ar arch
1.1       kristaps   76: Search only for a particular architecture.
1.3       kristaps   77: .It Fl s Ar cat
                     78: Search only for a manual section.
1.1       kristaps   79: See
                     80: .Xr man 1
1.3       kristaps   81: for a listing of manual sections.
1.4       kristaps   82: .El
                     83: .Pp
1.19      kristaps   84: .Nm whatis
                     85: considers an
1.4       kristaps   86: .Ar expression
1.19      kristaps   87: to consist of an opaque keyword.
                     88: .Nm apropos
                     89: parses a
                     90: .Ar expression
                     91: into type and keyword pairs.
1.18      kristaps   92: This pair syntax
1.4       kristaps   93: .Li [key[,key]*(=~)]?val ,
                     94: where operand
1.10      kristaps   95: .Cm key
1.4       kristaps   96: is an
                     97: .Xr mdoc 7
                     98: macro to query and
1.10      kristaps   99: .Cm val
1.4       kristaps  100: is its value.
1.10      kristaps  101: See
                    102: .Sx Macro Keys
                    103: for a list of available keys.
1.4       kristaps  104: Operator
                    105: .Li \&=
1.18      kristaps  106: evaluates a full string, while
1.4       kristaps  107: .Li \&~
1.18      kristaps  108: evaluates a
                    109: .Xr glob 7
                    110: pattern.
1.1       kristaps  111: .Pp
1.4       kristaps  112: Results are sorted by manual title, with output formatted as
1.18      kristaps  113: .Qq title(sec) \- description
                    114: where
1.1       kristaps  115: .Qq title
                    116: is the manual's title (note multiple manual names may exist for one
                    117: title),
1.3       kristaps  118: .Qq sec
                    119: is the manual section, and
1.1       kristaps  120: .Qq description
                    121: is the manual's short description.
                    122: If an architecture is specified for the manual, it is displayed as
1.18      kristaps  123: .Qq title(cat/arch) \- description .
1.10      kristaps  124: .Ss Macro Keys
1.19      kristaps  125: .Nm apropos
                    126: queries evaluate over a subset of
1.10      kristaps  127: .Xr mdoc 7
                    128: macros indexed by
                    129: .Xr mandocdb 8 .
                    130: In addition to the macro keys listed below, the special key
                    131: .Cm any
                    132: may be used to match any available macro key.
                    133: .Pp
                    134: Names and description:
                    135: .Bl -column "xLix" description -offset indent -compact
                    136: .It Li \&Nm Ta manual name
                    137: .It Li \&Nd Ta one-line manual description
                    138: .El
                    139: .Pp
                    140: Sections and cross references:
                    141: .Bl -column "xLix" description -offset indent -compact
                    142: .It Li \&Sh Ta section header (excluding standard sections)
                    143: .It Li \&Ss Ta subsection header
                    144: .It Li \&Xr Ta cross reference to another manual page
                    145: .It Li \&Rs Ta bibliographic reference
                    146: .El
                    147: .Pp
                    148: Semantic markup for command line utilities:
                    149: .Bl -column "xLix" description -offset indent -compact
                    150: .It Li \&Fl Ta command line options (flags)
                    151: .It Li \&Cm Ta command modifier
                    152: .It Li \&Ar Ta command argument
                    153: .It Li \&Ic Ta internal or interactive command
                    154: .It Li \&Ev Ta environmental variable
                    155: .It Li \&Pa Ta file system path
                    156: .El
                    157: .Pp
                    158: Semantic markup for function libraries:
                    159: .Bl -column "xLix" description -offset indent -compact
                    160: .It Li \&Lb Ta function library name
                    161: .It Li \&In Ta include file
                    162: .It Li \&Ft Ta function return type
                    163: .It Li \&Fn Ta function name
                    164: .It Li \&Fa Ta function argument type and name
                    165: .It Li \&Vt Ta variable type
                    166: .It Li \&Va Ta variable name
                    167: .It Li \&Dv Ta defined variable or preprocessor constant
                    168: .It Li \&Er Ta error constant
                    169: .It Li \&Ev Ta environmental variable
                    170: .El
                    171: .Pp
                    172: Various semantic markup:
                    173: .Bl -column "xLix" description -offset indent -compact
                    174: .It Li \&An Ta author name
                    175: .It Li \&Lk Ta hyperlink
                    176: .It Li \&Mt Ta Do mailto Dc hyperlink
                    177: .It Li \&Cd Ta kernel configuration declaration
                    178: .It Li \&Ms Ta mathematical symbol
                    179: .It Li \&Tn Ta tradename
                    180: .El
                    181: .Pp
                    182: Physical markup:
                    183: .Bl -column "xLix" description -offset indent -compact
                    184: .It Li \&Em Ta italic font or underline
                    185: .It Li \&Sy Ta boldface font
                    186: .It Li \&Li Ta typewriter font
                    187: .El
                    188: .Pp
                    189: Text production:
                    190: .Bl -column "xLix" description -offset indent -compact
                    191: .It Li \&St Ta reference to a standards document
                    192: .It Li \&At Ta At No version reference
                    193: .It Li \&Bx Ta Bx No version reference
                    194: .It Li \&Bsx Ta Bsx No version reference
                    195: .It Li \&Nx Ta Nx No version reference
                    196: .It Li \&Fx Ta Fx No version reference
                    197: .It Li \&Ox Ta Ox No version reference
                    198: .It Li \&Dx Ta Dx No version reference
                    199: .El
1.6       kristaps  200: .Sh ENVIRONMENT
                    201: .Bl -tag -width Ds
                    202: .It Ev MANPATH
1.14      kristaps  203: Colon-separated paths modifying the default list of paths searched for
1.6       kristaps  204: manual databases.
                    205: Invalid paths, or paths without manual databases, are ignored.
1.9       schwarze  206: Overridden by
1.7       kristaps  207: .Fl M .
1.14      kristaps  208: If
                    209: .Ev MANPATH
                    210: begins with a
                    211: .Sq \&: ,
                    212: it is appended to the default list;
                    213: else if it ends with
                    214: .Sq \&: ,
                    215: it is prepended to the default list; else if it contains
                    216: .Sq \&:: ,
                    217: the default list is inserted between the colons.
                    218: If none of these conditions are met, it overrides the default list.
1.13      schwarze  219: .El
                    220: .Sh FILES
                    221: .Bl -tag -width "/etc/man.conf" -compact
1.19      kristaps  222: .It Pa mandocdb.db
1.13      schwarze  223: name of the
                    224: .Xr mandocdb 8
                    225: keyword database
                    226: .It Pa /etc/man.conf
                    227: default
                    228: .Xr man 1
                    229: configuration file
1.6       kristaps  230: .El
1.1       kristaps  231: .Sh EXIT STATUS
                    232: .Ex -std
                    233: .Sh EXAMPLES
                    234: Search for
1.4       kristaps  235: .Qq mdoc
1.18      kristaps  236: as a word or
                    237: .Xr glob 7
                    238: expression:
1.4       kristaps  239: .Pp
                    240: .Dl $ apropos mdoc
1.18      kristaps  241: .Dl $ apropos any~mdoc*
1.4       kristaps  242: .Pp
1.11      kristaps  243: Include matches for
                    244: .Qq roff
                    245: and
1.4       kristaps  246: .Qq man
1.18      kristaps  247: using
                    248: .Xr glob 7
                    249: expressions:
1.4       kristaps  250: .Pp
1.18      kristaps  251: .Dl $ apropos ~*mdoc* ~*roff*
1.4       kristaps  252: .Pp
                    253: Search for
                    254: .Qq optarg
1.18      kristaps  255: as a variable name in the library category:
1.1       kristaps  256: .Pp
1.18      kristaps  257: .Dl $ apropos \-s 3 Va=optarg
1.1       kristaps  258: .Sh SEE ALSO
1.18      kristaps  259: .Xr glob 7 ,
1.11      kristaps  260: .Xr mandocdb 8
1.1       kristaps  261: .Sh AUTHORS
                    262: The
                    263: .Nm
                    264: utility was written by
1.2       kristaps  265: .An Kristaps Dzonsons ,
                    266: .Mt kristaps@bsd.lv .

CVSweb