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