Annotation of src/usr.bin/mandoc/apropos.1, Revision 1.27
1.27 ! schwarze 1: .\" $OpenBSD$
1.1 schwarze 2: .\"
1.25 schwarze 3: .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
1.21 schwarze 4: .\" Copyright (c) 2011, 2012, 2014 Ingo Schwarze <schwarze@openbsd.org>
1.1 schwarze 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.27 ! schwarze 18: .Dd $Mdocdate: August 30 2014 $
1.1 schwarze 19: .Dt APROPOS 1
20: .Os
21: .Sh NAME
1.25 schwarze 22: .Nm apropos ,
23: .Nm whatis
1.6 schwarze 24: .Nd search manual page databases
1.1 schwarze 25: .Sh SYNOPSIS
26: .Nm
1.27 ! schwarze 27: .Op Fl acfhklVw
1.9 schwarze 28: .Op Fl C Ar file
1.13 schwarze 29: .Op Fl M Ar path
30: .Op Fl m Ar path
1.20 schwarze 31: .Op Fl O Ar outkey
1.3 schwarze 32: .Op Fl S Ar arch
33: .Op Fl s Ar section
1.9 schwarze 34: .Ar expression ...
1.1 schwarze 35: .Sh DESCRIPTION
36: The
1.25 schwarze 37: .Nm apropos
38: and
39: .Nm whatis
40: utilities query manual page databases generated by
1.16 schwarze 41: .Xr makewhatis 8 ,
1.23 schwarze 42: evaluating
1.4 schwarze 43: .Ar expression
1.6 schwarze 44: for each file in each database.
1.25 schwarze 45: By default, they display the names, section numbers, and description lines
1.23 schwarze 46: of all matching manuals.
1.12 schwarze 47: .Pp
48: By default,
49: .Nm
50: searches for
1.16 schwarze 51: .Xr makewhatis 8
1.12 schwarze 52: databases in the default paths stipulated by
1.23 schwarze 53: .Xr man 1
54: and uses case-insensitive substring matching
55: .Pq the Cm = No operator
1.12 schwarze 56: over manual names and descriptions
57: .Pq the Li \&Nm No and Li \&Nd No macro keys .
58: Multiple terms imply pairwise
59: .Fl o .
60: .Pp
1.25 schwarze 61: .Nm whatis
62: is a synonym for
63: .Nm
64: .Fl f .
65: .Pp
66: The options are as follows:
1.1 schwarze 67: .Bl -tag -width Ds
1.25 schwarze 68: .It Fl a
69: Instead of showing only the title lines, show the complete manual pages,
70: just like
71: .Xr man 1
72: .Fl a
73: would.
74: If the standard output is a terminal device and
75: .Fl c
76: is not specified, use
77: .Xr more 1
78: to paginate them.
79: In
80: .Fl a
81: mode, the options
82: .Fl IOTW
83: described in the
84: .Xr mandoc 1
85: manual are also available.
1.9 schwarze 86: .It Fl C Ar file
87: Specify an alternative configuration
88: .Ar file
89: in
90: .Xr man.conf 5
91: format.
1.25 schwarze 92: .It Fl c
93: In
94: .Fl a
95: mode, copy the formatted manual pages to the standard output without using
96: .Xr more 1
97: to paginate them.
98: .It Fl f
99: Search for all words in
100: .Ar expression
101: in manual page names only.
102: The search is case insensitive and matches whole words only.
103: In this mode, macro keys, comparison operators, and logical operators
104: are not available.
105: This overrides any earlier
106: .Fl k
1.26 schwarze 107: and
108: .Fl l
109: options.
1.27 ! schwarze 110: .It Fl h
! 111: Instead of showing the title lines, show the SYNOPSIS sections, just like
! 112: .Xr man 1
! 113: .Fl h
! 114: would.
1.25 schwarze 115: .It Fl k
116: Support the full
117: .Ar expression
118: syntax.
119: This overrides any earlier
120: .Fl f
1.26 schwarze 121: and
122: .Fl l
123: options.
1.25 schwarze 124: It is the default for
125: .Nm .
1.26 schwarze 126: .It Fl l
127: An alias for
128: .Xr mandoc 1
129: .Fl a .
130: This overrides any earlier
131: .Fl f ,
132: .Fl k ,
133: and
134: .Fl w
135: options.
1.13 schwarze 136: .It Fl M Ar path
1.6 schwarze 137: Use the colon-separated path instead of the default list of paths
138: searched for
1.16 schwarze 139: .Xr makewhatis 8
1.6 schwarze 140: databases.
141: Invalid paths, or paths without manual databases, are ignored.
1.13 schwarze 142: .It Fl m Ar path
1.6 schwarze 143: Prepend the colon-separated paths to the list of paths searched
144: for
1.16 schwarze 145: .Xr makewhatis 8
1.6 schwarze 146: databases.
147: Invalid paths, or paths without manual databases, are ignored.
1.20 schwarze 148: .It Fl O Ar outkey
149: Show the values associated with the key
150: .Ar outkey
151: instead of the manual descriptions.
1.3 schwarze 152: .It Fl S Ar arch
1.13 schwarze 153: Restrict the search to pages for the specified
154: .Xr machine 1
155: architecture.
156: .Ar arch
157: is case insensitive.
158: By default, pages for all architectures are shown.
159: .It Fl s Ar section
160: Restrict the search to the specified section of the manual.
161: By default, pages from all sections are shown.
1.1 schwarze 162: See
163: .Xr man 1
1.13 schwarze 164: for a listing of sections.
1.26 schwarze 165: .It Fl V
166: Print version and exit.
1.25 schwarze 167: .It Fl w
168: Instead of showing title lines, show the pathnames of the matching
169: manual pages, just like
170: .Xr man 1
171: .Fl w
172: would.
1.4 schwarze 173: .El
174: .Pp
175: An
176: .Ar expression
177: consists of search terms joined by logical operators
178: .Fl a
179: .Pq and
180: and
181: .Fl o
182: .Pq or .
183: The
184: .Fl a
185: operator has precedence over
186: .Fl o
187: and both are evaluated left-to-right.
188: .Bl -tag -width Ds
189: .It \&( Ar expr No \&)
190: True if the subexpression
191: .Ar expr
192: is true.
193: .It Ar expr1 Fl a Ar expr2
194: True if both
195: .Ar expr1
196: and
197: .Ar expr2
198: are true (logical
1.23 schwarze 199: .Sq and ) .
1.4 schwarze 200: .It Ar expr1 Oo Fl o Oc Ar expr2
201: True if
202: .Ar expr1
203: and/or
204: .Ar expr2
205: evaluate to true (logical
1.23 schwarze 206: .Sq or ) .
1.4 schwarze 207: .It Ar term
208: True if
209: .Ar term
210: is satisfied.
211: This has syntax
1.23 schwarze 212: .Sm off
213: .Oo
214: .Op Ar key Op , Ar key ...
215: .Pq Cm = | ~
216: .Oc
1.24 schwarze 217: .Ar val ,
218: .Sm on
1.23 schwarze 219: where
220: .Ar key
1.4 schwarze 221: is an
222: .Xr mdoc 7
223: macro to query and
1.23 schwarze 224: .Ar val
1.4 schwarze 225: is its value.
1.7 schwarze 226: See
227: .Sx Macro Keys
228: for a list of available keys.
1.4 schwarze 229: Operator
1.23 schwarze 230: .Cm =
1.4 schwarze 231: evaluates a substring, while
1.23 schwarze 232: .Cm ~
1.4 schwarze 233: evaluates a regular expression.
234: .It Fl i Ar term
1.8 schwarze 235: If
1.4 schwarze 236: .Ar term
1.8 schwarze 237: is a regular expression, it
1.4 schwarze 238: is evaluated case-insensitively.
1.8 schwarze 239: Has no effect on substring terms.
1.1 schwarze 240: .El
241: .Pp
1.23 schwarze 242: Results are sorted by manual sections and names, with output formatted as
1.1 schwarze 243: .Pp
1.23 schwarze 244: .D1 name[, name...](sec) \- description
1.1 schwarze 245: .Pp
246: Where
1.23 schwarze 247: .Dq name
248: is the manual's name,
249: .Dq sec
1.3 schwarze 250: is the manual section, and
1.23 schwarze 251: .Dq description
1.1 schwarze 252: is the manual's short description.
253: If an architecture is specified for the manual, it is displayed as
254: .Pp
1.23 schwarze 255: .D1 name(sec/arch) \- description
1.1 schwarze 256: .Pp
257: Resulting manuals may be accessed as
258: .Pp
1.23 schwarze 259: .Dl $ man \-s sec name
1.1 schwarze 260: .Pp
261: If an architecture is specified in the output, use
262: .Pp
1.23 schwarze 263: .Dl $ man \-s sec \-S arch name
1.7 schwarze 264: .Ss Macro Keys
265: Queries evaluate over a subset of
266: .Xr mdoc 7
267: macros indexed by
1.16 schwarze 268: .Xr makewhatis 8 .
1.7 schwarze 269: In addition to the macro keys listed below, the special key
270: .Cm any
271: may be used to match any available macro key.
272: .Pp
273: Names and description:
274: .Bl -column "xLix" description -offset indent -compact
275: .It Li \&Nm Ta manual name
276: .It Li \&Nd Ta one-line manual description
1.20 schwarze 277: .It Li arch Ta machine architecture (case-insensitive)
278: .It Li sec Ta manual section number
1.7 schwarze 279: .El
280: .Pp
281: Sections and cross references:
282: .Bl -column "xLix" description -offset indent -compact
283: .It Li \&Sh Ta section header (excluding standard sections)
284: .It Li \&Ss Ta subsection header
285: .It Li \&Xr Ta cross reference to another manual page
286: .It Li \&Rs Ta bibliographic reference
287: .El
288: .Pp
289: Semantic markup for command line utilities:
290: .Bl -column "xLix" description -offset indent -compact
291: .It Li \&Fl Ta command line options (flags)
292: .It Li \&Cm Ta command modifier
293: .It Li \&Ar Ta command argument
294: .It Li \&Ic Ta internal or interactive command
295: .It Li \&Ev Ta environmental variable
296: .It Li \&Pa Ta file system path
297: .El
298: .Pp
299: Semantic markup for function libraries:
300: .Bl -column "xLix" description -offset indent -compact
301: .It Li \&Lb Ta function library name
302: .It Li \&In Ta include file
303: .It Li \&Ft Ta function return type
304: .It Li \&Fn Ta function name
305: .It Li \&Fa Ta function argument type and name
306: .It Li \&Vt Ta variable type
307: .It Li \&Va Ta variable name
308: .It Li \&Dv Ta defined variable or preprocessor constant
309: .It Li \&Er Ta error constant
310: .It Li \&Ev Ta environmental variable
311: .El
312: .Pp
313: Various semantic markup:
314: .Bl -column "xLix" description -offset indent -compact
315: .It Li \&An Ta author name
316: .It Li \&Lk Ta hyperlink
317: .It Li \&Mt Ta Do mailto Dc hyperlink
318: .It Li \&Cd Ta kernel configuration declaration
319: .It Li \&Ms Ta mathematical symbol
320: .It Li \&Tn Ta tradename
321: .El
322: .Pp
323: Physical markup:
324: .Bl -column "xLix" description -offset indent -compact
325: .It Li \&Em Ta italic font or underline
326: .It Li \&Sy Ta boldface font
327: .It Li \&Li Ta typewriter font
328: .El
329: .Pp
330: Text production:
331: .Bl -column "xLix" description -offset indent -compact
332: .It Li \&St Ta reference to a standards document
333: .It Li \&At Ta At No version reference
334: .It Li \&Bx Ta Bx No version reference
335: .It Li \&Bsx Ta Bsx No version reference
336: .It Li \&Nx Ta Nx No version reference
337: .It Li \&Fx Ta Fx No version reference
338: .It Li \&Ox Ta Ox No version reference
339: .It Li \&Dx Ta Dx No version reference
340: .El
1.6 schwarze 341: .Sh ENVIRONMENT
1.25 schwarze 342: .Bl -tag -width MANPAGER
343: .It Ev MANPAGER
344: Any non-empty value of the environment variable
345: .Ev MANPAGER
346: will be used instead of the standard pagination program,
347: .Xr more 1 .
1.6 schwarze 348: .It Ev MANPATH
1.13 schwarze 349: The standard search path used by
350: .Xr man 1
351: may be changed by specifying a path in the
352: .Ev MANPATH
353: environment variable.
1.6 schwarze 354: Invalid paths, or paths without manual databases, are ignored.
355: Overridden by
356: .Fl M .
1.10 schwarze 357: If
358: .Ev MANPATH
1.13 schwarze 359: begins with a colon, it is appended to the default list;
360: if it ends with a colon, it is prepended to the default list;
361: or if it contains two adjacent colons,
362: the standard search path is inserted between the colons.
363: If none of these conditions are met, it overrides the
364: standard search path.
1.25 schwarze 365: .It Ev PAGER
366: Specifies the pagination program to use when
367: .Ev MANPAGER
368: is not defined.
369: If neither PAGER nor MANPAGER is defined,
370: .Pa /usr/bin/more Fl s
371: will be used.
1.9 schwarze 372: .El
373: .Sh FILES
374: .Bl -tag -width "/etc/man.conf" -compact
1.15 schwarze 375: .It Pa mandoc.db
1.9 schwarze 376: name of the
1.16 schwarze 377: .Xr makewhatis 8
1.9 schwarze 378: keyword database
379: .It Pa /etc/man.conf
380: default
381: .Xr man 1
382: configuration file
1.6 schwarze 383: .El
1.1 schwarze 384: .Sh EXIT STATUS
385: .Ex -std
386: .Sh EXAMPLES
387: Search for
1.14 schwarze 388: .Qq .cf
389: as a substring of manual names and descriptions:
1.4 schwarze 390: .Pp
1.14 schwarze 391: .Dl $ apropos .cf
1.4 schwarze 392: .Pp
1.8 schwarze 393: Include matches for
1.14 schwarze 394: .Qq .cnf
1.8 schwarze 395: and
1.14 schwarze 396: .Qq .conf
397: as well:
1.4 schwarze 398: .Pp
1.14 schwarze 399: .Dl $ apropos .cf .cnf .conf
1.4 schwarze 400: .Pp
1.14 schwarze 401: Search in names and descriptions using a regular expression:
402: .Pp
403: .Dl $ apropos '~set.?[ug]id'
404: .Pp
1.23 schwarze 405: Search for manuals in the library section mentioning both the
1.1 schwarze 406: .Qq optind
1.14 schwarze 407: and the
1.4 schwarze 408: .Qq optarg
1.14 schwarze 409: variables:
410: .Pp
411: .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
412: .Pp
413: Do exactly the same as calling
414: .Xr whatis 1
415: with the argument
416: .Qq ssh :
1.1 schwarze 417: .Pp
1.14 schwarze 418: .Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]'
1.20 schwarze 419: .Pp
420: The following two invocations are equivalent:
421: .Pp
422: .D1 Li $ apropos -S Ar arch Li -s Ar section expression
423: .Bd -ragged -offset indent
424: .Li $ apropos \e( Ar expression Li \e)
425: .Li -a arch~^( Ns Ar arch Ns Li |any)$
426: .Li -a sec~^ Ns Ar section Ns Li $
427: .Ed
1.1 schwarze 428: .Sh SEE ALSO
429: .Xr man 1 ,
1.8 schwarze 430: .Xr re_format 7 ,
1.16 schwarze 431: .Xr makewhatis 8
1.17 schwarze 432: .Sh HISTORY
1.25 schwarze 433: Part of the functionality of
434: .Nm whatis
435: was already provided by the former
436: .Nm manwhere
437: utility in
438: .Bx 1 .
439: The
1.17 schwarze 440: .Nm
1.25 schwarze 441: and
442: .Nm whatis
443: utilities first appeared in
1.17 schwarze 444: .Bx 2 .
1.25 schwarze 445: They were rewritten from scratch for
1.20 schwarze 446: .Ox 5.6 .
1.17 schwarze 447: .Pp
448: The
449: .Fl M
450: option and the
451: .Ev MANPATH
452: variable first appeared in
453: .Bx 4.3 ;
454: .Fl m
455: in
456: .Bx 4.3 Reno ;
457: .Fl C
458: in
459: .Bx 4.4 Lite1 ;
460: and
461: .Fl S
462: and
463: .Fl s
464: in
1.25 schwarze 465: .Ox 4.5
466: for
467: .Nm
468: and in
469: .Ox 5.6
470: for
471: .Nm whatis .
1.1 schwarze 472: .Sh AUTHORS
1.17 schwarze 473: .An -nosplit
474: .An Bill Joy
1.25 schwarze 475: wrote
476: .Nm manwhere
477: in 1977 and the original
1.17 schwarze 478: .Bx
1.1 schwarze 479: .Nm
1.25 schwarze 480: and
481: .Nm whatis
1.17 schwarze 482: in February 1979.
483: The current version was written by
1.20 schwarze 484: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
485: and
486: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .