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

Annotation of mandoc/apropos.1, Revision 1.50

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

CVSweb