Annotation of mandoc/apropos.1, Revision 1.23
1.23 ! schwarze 1: .\" $Id: apropos.1,v 1.22 2013/10/01 20:56:18 schwarze 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.23 ! schwarze 17: .Dd $Mdocdate: October 1 2013 $
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.23 ! schwarze 48: .Xr man 1 ,
! 49: parses terms as case-sensitive regular expressions
! 50: .Pq the Li \&~ operator
! 51: over manual names and descriptions
! 52: .Pq the Li \&Nm No and Li \&Nd No macro keys .
! 53: Multiple terms imply pairwise
! 54: .Fl o .
1.19 kristaps 55: .Nm whatis
56: maps terms only to case-sensitive manual names.
1.16 kristaps 57: .Pp
1.1 kristaps 58: Its arguments are as follows:
59: .Bl -tag -width Ds
1.13 schwarze 60: .It Fl C Ar file
61: Specify an alternative configuration
62: .Ar file
63: in
64: .Xr man.conf 5
65: format.
1.20 schwarze 66: .It Fl M Ar path
1.7 kristaps 67: Use the colon-separated path instead of the default list of paths
68: searched for
69: .Xr mandocdb 8
70: databases.
71: Invalid paths, or paths without manual databases, are ignored.
1.20 schwarze 72: .It Fl m Ar path
1.9 schwarze 73: Prepend the colon-separated paths to the list of paths searched
1.6 kristaps 74: for
1.5 kristaps 75: .Xr mandocdb 8
76: databases.
1.6 kristaps 77: Invalid paths, or paths without manual databases, are ignored.
1.3 kristaps 78: .It Fl S Ar arch
1.23 ! schwarze 79: Restrict the search to pages for the specified
! 80: .Xr machine 1
! 81: architecture.
! 82: .Ar arch
! 83: is case insensitive.
! 84: By default, pages for all architectures are shown.
! 85: .It Fl s Ar section
! 86: Restrict the search to the specified section of the manual.
! 87: By default, pages from all sections are shown.
1.1 kristaps 88: See
89: .Xr man 1
1.23 ! schwarze 90: for a listing of sections.
1.4 kristaps 91: .El
92: .Pp
1.23 ! schwarze 93: An
1.4 kristaps 94: .Ar expression
1.23 ! schwarze 95: consists of search terms joined by logical operators
! 96: .Fl a
! 97: .Pq and
! 98: and
! 99: .Fl o
! 100: .Pq or .
! 101: The
! 102: .Fl a
! 103: operator has precedence over
! 104: .Fl o
! 105: and both are evaluated left-to-right.
! 106: .Bl -tag -width Ds
! 107: .It \&( Ar expr No \&)
! 108: True if the subexpression
! 109: .Ar expr
! 110: is true.
! 111: .It Ar expr1 Fl a Ar expr2
! 112: True if both
! 113: .Ar expr1
! 114: and
! 115: .Ar expr2
! 116: are true (logical
! 117: .Qq and ) .
! 118: .It Ar expr1 Oo Fl o Oc Ar expr2
! 119: True if
! 120: .Ar expr1
! 121: and/or
! 122: .Ar expr2
! 123: evaluate to true (logical
! 124: .Qq or ) .
! 125: .It Ar term
! 126: True if
! 127: .Ar term
! 128: is satisfied.
! 129: This has syntax
1.4 kristaps 130: .Li [key[,key]*(=~)]?val ,
131: where operand
1.10 kristaps 132: .Cm key
1.4 kristaps 133: is an
134: .Xr mdoc 7
135: macro to query and
1.10 kristaps 136: .Cm val
1.4 kristaps 137: is its value.
1.10 kristaps 138: See
139: .Sx Macro Keys
140: for a list of available keys.
1.4 kristaps 141: Operator
142: .Li \&=
1.23 ! schwarze 143: evaluates a substring, while
1.4 kristaps 144: .Li \&~
1.23 ! schwarze 145: evaluates a regular expression.
! 146: .It Fl i Ar term
! 147: If
! 148: .Ar term
! 149: is a regular expression, it
! 150: is evaluated case-insensitively.
! 151: Has no effect on substring terms.
! 152: .El
! 153: .Pp
! 154: .Nm whatis
! 155: considers an
! 156: .Ar expression
! 157: to consist of an opaque keyword.
1.1 kristaps 158: .Pp
1.4 kristaps 159: Results are sorted by manual title, with output formatted as
1.23 ! schwarze 160: .Pp
! 161: .D1 title(sec) \- description
! 162: .Pp
! 163: Where
1.1 kristaps 164: .Qq title
165: is the manual's title (note multiple manual names may exist for one
166: title),
1.3 kristaps 167: .Qq sec
168: is the manual section, and
1.1 kristaps 169: .Qq description
170: is the manual's short description.
171: If an architecture is specified for the manual, it is displayed as
1.23 ! schwarze 172: .Pp
! 173: .D1 title(cat/arch) \- description
! 174: .Pp
! 175: Resulting manuals may be accessed as
! 176: .Pp
! 177: .Dl $ man \-s sec title
! 178: .Pp
! 179: If an architecture is specified in the output, use
! 180: .Pp
! 181: .Dl $ man \-s sec \-S arch title
1.10 kristaps 182: .Ss Macro Keys
1.23 ! schwarze 183: Queries evaluate over a subset of
1.10 kristaps 184: .Xr mdoc 7
185: macros indexed by
186: .Xr mandocdb 8 .
187: In addition to the macro keys listed below, the special key
188: .Cm any
189: may be used to match any available macro key.
190: .Pp
191: Names and description:
192: .Bl -column "xLix" description -offset indent -compact
193: .It Li \&Nm Ta manual name
194: .It Li \&Nd Ta one-line manual description
195: .El
196: .Pp
197: Sections and cross references:
198: .Bl -column "xLix" description -offset indent -compact
199: .It Li \&Sh Ta section header (excluding standard sections)
200: .It Li \&Ss Ta subsection header
201: .It Li \&Xr Ta cross reference to another manual page
202: .It Li \&Rs Ta bibliographic reference
203: .El
204: .Pp
205: Semantic markup for command line utilities:
206: .Bl -column "xLix" description -offset indent -compact
207: .It Li \&Fl Ta command line options (flags)
208: .It Li \&Cm Ta command modifier
209: .It Li \&Ar Ta command argument
210: .It Li \&Ic Ta internal or interactive command
211: .It Li \&Ev Ta environmental variable
212: .It Li \&Pa Ta file system path
213: .El
214: .Pp
215: Semantic markup for function libraries:
216: .Bl -column "xLix" description -offset indent -compact
217: .It Li \&Lb Ta function library name
218: .It Li \&In Ta include file
219: .It Li \&Ft Ta function return type
220: .It Li \&Fn Ta function name
221: .It Li \&Fa Ta function argument type and name
222: .It Li \&Vt Ta variable type
223: .It Li \&Va Ta variable name
224: .It Li \&Dv Ta defined variable or preprocessor constant
225: .It Li \&Er Ta error constant
226: .It Li \&Ev Ta environmental variable
227: .El
228: .Pp
229: Various semantic markup:
230: .Bl -column "xLix" description -offset indent -compact
231: .It Li \&An Ta author name
232: .It Li \&Lk Ta hyperlink
233: .It Li \&Mt Ta Do mailto Dc hyperlink
234: .It Li \&Cd Ta kernel configuration declaration
235: .It Li \&Ms Ta mathematical symbol
236: .It Li \&Tn Ta tradename
237: .El
238: .Pp
239: Physical markup:
240: .Bl -column "xLix" description -offset indent -compact
241: .It Li \&Em Ta italic font or underline
242: .It Li \&Sy Ta boldface font
243: .It Li \&Li Ta typewriter font
244: .El
245: .Pp
246: Text production:
247: .Bl -column "xLix" description -offset indent -compact
248: .It Li \&St Ta reference to a standards document
249: .It Li \&At Ta At No version reference
250: .It Li \&Bx Ta Bx No version reference
251: .It Li \&Bsx Ta Bsx No version reference
252: .It Li \&Nx Ta Nx No version reference
253: .It Li \&Fx Ta Fx No version reference
254: .It Li \&Ox Ta Ox No version reference
255: .It Li \&Dx Ta Dx No version reference
256: .El
1.6 kristaps 257: .Sh ENVIRONMENT
1.23 ! schwarze 258: .Bl -tag -width MANPATH
1.6 kristaps 259: .It Ev MANPATH
1.23 ! schwarze 260: The standard search path used by
! 261: .Xr man 1
! 262: may be changed by specifying a path in the
! 263: .Ev MANPATH
! 264: environment variable.
1.6 kristaps 265: Invalid paths, or paths without manual databases, are ignored.
1.9 schwarze 266: Overridden by
1.7 kristaps 267: .Fl M .
1.14 kristaps 268: If
269: .Ev MANPATH
1.23 ! schwarze 270: begins with a colon, it is appended to the default list;
! 271: if it ends with a colon, it is prepended to the default list;
! 272: or if it contains two adjacent colons,
! 273: the standard search path is inserted between the colons.
! 274: If none of these conditions are met, it overrides the
! 275: standard search path.
1.13 schwarze 276: .El
277: .Sh FILES
278: .Bl -tag -width "/etc/man.conf" -compact
1.22 schwarze 279: .It Pa mandoc.db
1.13 schwarze 280: name of the
281: .Xr mandocdb 8
282: keyword database
283: .It Pa /etc/man.conf
284: default
285: .Xr man 1
286: configuration file
1.6 kristaps 287: .El
1.1 kristaps 288: .Sh EXIT STATUS
289: .Ex -std
290: .Sh EXAMPLES
291: Search for
1.23 ! schwarze 292: .Qq .cf
! 293: as a substring of manual names and descriptions:
1.4 kristaps 294: .Pp
1.23 ! schwarze 295: .Dl $ apropos .cf
1.4 kristaps 296: .Pp
1.11 kristaps 297: Include matches for
1.23 ! schwarze 298: .Qq .cnf
1.11 kristaps 299: and
1.23 ! schwarze 300: .Qq .conf
! 301: as well:
! 302: .Pp
! 303: .Dl $ apropos .cf .cnf .conf
! 304: .Pp
! 305: Search in names and descriptions using a regular expression:
1.4 kristaps 306: .Pp
1.23 ! schwarze 307: .Dl $ apropos '~set.?[ug]id'
1.4 kristaps 308: .Pp
1.23 ! schwarze 309: Search for manuals in the library category mentioning both the
! 310: .Qq optind
! 311: and the
1.4 kristaps 312: .Qq optarg
1.23 ! schwarze 313: variables:
! 314: .Pp
! 315: .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
1.1 kristaps 316: .Pp
1.23 ! schwarze 317: Do exactly the same as calling
! 318: .Xr whatis 1
! 319: with the argument
! 320: .Qq ssh :
! 321: .Pp
! 322: .Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]'
1.1 kristaps 323: .Sh SEE ALSO
1.23 ! schwarze 324: .Xr man 1 ,
! 325: .Xr re_format 7 ,
1.11 kristaps 326: .Xr mandocdb 8
1.23 ! schwarze 327: .Sh HISTORY
! 328: An
! 329: .Nm
! 330: utility first appeared in
! 331: .Bx 2 .
! 332: It was rewritten from scratch for
! 333: .Ox 5.1 .
! 334: .Pp
! 335: The
! 336: .Fl M
! 337: option and the
! 338: .Ev MANPATH
! 339: variable first appeared in
! 340: .Bx 4.3 ;
! 341: .Fl m
! 342: in
! 343: .Bx 4.3 Reno ;
! 344: .Fl C
! 345: in
! 346: .Bx 4.4 Lite1 ;
! 347: and
! 348: .Fl S
! 349: and
! 350: .Fl s
! 351: in
! 352: .Ox 4.5 .
1.1 kristaps 353: .Sh AUTHORS
1.23 ! schwarze 354: .An -nosplit
! 355: .An Bill Joy
! 356: wrote the original
! 357: .Bx
1.1 kristaps 358: .Nm
1.23 ! schwarze 359: in February 1979.
! 360: The current version was written by
1.21 schwarze 361: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to apropos.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc