Annotation of mandoc/apropos.1, Revision 1.47
1.47 ! schwarze 1: .\" $Id: apropos.1,v 1.46 2017/07/04 23:40:01 schwarze Exp $
1.1 kristaps 2: .\"
1.17 kristaps 3: .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
1.41 schwarze 4: .\" Copyright (c) 2011, 2012, 2014, 2017 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.47 ! schwarze 18: .Dd $Mdocdate: July 4 2017 $
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
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.
1.32 schwarze 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
1.36 schwarze 82: .Fl IKOTW
1.31 schwarze 83: described in the
84: .Xr mandoc 1
85: manual are also available.
1.13 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.31 schwarze 92: .It Fl f
93: Search for all words in
94: .Ar expression
95: in manual page names only.
96: The search is case insensitive and matches whole words only.
97: In this mode, macro keys, comparison operators, and logical operators
98: are not available.
99: .It Fl k
100: Support the full
101: .Ar expression
102: syntax.
103: It is the default for
104: .Nm .
1.20 schwarze 105: .It Fl M Ar path
1.7 kristaps 106: Use the colon-separated path instead of the default list of paths
107: searched for
1.28 schwarze 108: .Xr makewhatis 8
1.7 kristaps 109: databases.
110: Invalid paths, or paths without manual databases, are ignored.
1.20 schwarze 111: .It Fl m Ar path
1.9 schwarze 112: Prepend the colon-separated paths to the list of paths searched
1.6 kristaps 113: for
1.28 schwarze 114: .Xr makewhatis 8
1.5 kristaps 115: databases.
1.6 kristaps 116: Invalid paths, or paths without manual databases, are ignored.
1.24 schwarze 117: .It Fl O Ar outkey
118: Show the values associated with the key
119: .Ar outkey
120: instead of the manual descriptions.
1.3 kristaps 121: .It Fl S Ar arch
1.23 schwarze 122: Restrict the search to pages for the specified
123: .Xr machine 1
124: architecture.
125: .Ar arch
126: is case insensitive.
127: By default, pages for all architectures are shown.
128: .It Fl s Ar section
129: Restrict the search to the specified section of the manual.
130: By default, pages from all sections are shown.
1.1 kristaps 131: See
132: .Xr man 1
1.23 schwarze 133: for a listing of sections.
1.4 kristaps 134: .El
1.43 schwarze 135: .Pp
136: The options
137: .Fl chlw
138: are also supported and are documented in
139: .Xr man 1 .
1.44 schwarze 140: The options
141: .Fl fkl
142: are mutually exclusive and override each other.
1.4 kristaps 143: .Pp
1.23 schwarze 144: An
1.4 kristaps 145: .Ar expression
1.23 schwarze 146: consists of search terms joined by logical operators
147: .Fl a
148: .Pq and
149: and
150: .Fl o
151: .Pq or .
152: The
153: .Fl a
154: operator has precedence over
155: .Fl o
156: and both are evaluated left-to-right.
157: .Bl -tag -width Ds
158: .It \&( Ar expr No \&)
159: True if the subexpression
160: .Ar expr
161: is true.
162: .It Ar expr1 Fl a Ar expr2
163: True if both
164: .Ar expr1
165: and
166: .Ar expr2
167: are true (logical
1.27 schwarze 168: .Sq and ) .
1.23 schwarze 169: .It Ar expr1 Oo Fl o Oc Ar expr2
170: True if
171: .Ar expr1
172: and/or
173: .Ar expr2
174: evaluate to true (logical
1.27 schwarze 175: .Sq or ) .
1.23 schwarze 176: .It Ar term
177: True if
178: .Ar term
179: is satisfied.
180: This has syntax
1.27 schwarze 181: .Sm off
182: .Oo
183: .Op Ar key Op , Ar key ...
1.38 schwarze 184: .Pq Cm = | \(ti
1.27 schwarze 185: .Oc
1.29 schwarze 186: .Ar val ,
187: .Sm on
1.27 schwarze 188: where
189: .Ar key
1.4 kristaps 190: is an
191: .Xr mdoc 7
192: macro to query and
1.27 schwarze 193: .Ar val
1.4 kristaps 194: is its value.
1.10 kristaps 195: See
196: .Sx Macro Keys
197: for a list of available keys.
1.4 kristaps 198: Operator
1.27 schwarze 199: .Cm =
1.23 schwarze 200: evaluates a substring, while
1.38 schwarze 201: .Cm \(ti
1.23 schwarze 202: evaluates a regular expression.
203: .It Fl i Ar term
204: If
205: .Ar term
206: is a regular expression, it
207: is evaluated case-insensitively.
208: Has no effect on substring terms.
209: .El
1.1 kristaps 210: .Pp
1.41 schwarze 211: Results are sorted according to the following criteria:
212: .Bl -enum
213: .It
214: The manpath directory tree the page is found in, according to the
215: order specified with
216: .Fl M ,
217: .Fl m ,
218: the
219: .Ev MANPATH
220: environment variable, the
221: .Xr man.conf 5
222: configuration file, or the default documented in
223: .Xr man.conf 5 .
224: .It
225: The section number in ascending numerical order.
226: .It
227: The page name in ascending
228: .Xr ascii 7
229: alphabetical order, case-insensitive.
230: .El
231: .Pp
232: Each output line is formatted as
1.23 schwarze 233: .Pp
1.27 schwarze 234: .D1 name[, name...](sec) \- description
1.23 schwarze 235: .Pp
236: Where
1.27 schwarze 237: .Dq name
238: is the manual's name,
239: .Dq sec
1.3 kristaps 240: is the manual section, and
1.27 schwarze 241: .Dq description
1.1 kristaps 242: is the manual's short description.
243: If an architecture is specified for the manual, it is displayed as
1.23 schwarze 244: .Pp
1.27 schwarze 245: .D1 name(sec/arch) \- description
1.23 schwarze 246: .Pp
247: Resulting manuals may be accessed as
248: .Pp
1.27 schwarze 249: .Dl $ man \-s sec name
1.23 schwarze 250: .Pp
251: If an architecture is specified in the output, use
252: .Pp
1.27 schwarze 253: .Dl $ man \-s sec \-S arch name
1.10 kristaps 254: .Ss Macro Keys
1.23 schwarze 255: Queries evaluate over a subset of
1.10 kristaps 256: .Xr mdoc 7
257: macros indexed by
1.28 schwarze 258: .Xr makewhatis 8 .
1.10 kristaps 259: In addition to the macro keys listed below, the special key
260: .Cm any
261: may be used to match any available macro key.
262: .Pp
263: Names and description:
264: .Bl -column "xLix" description -offset indent -compact
265: .It Li \&Nm Ta manual name
266: .It Li \&Nd Ta one-line manual description
1.24 schwarze 267: .It Li arch Ta machine architecture (case-insensitive)
268: .It Li sec Ta manual section number
1.10 kristaps 269: .El
270: .Pp
271: Sections and cross references:
272: .Bl -column "xLix" description -offset indent -compact
273: .It Li \&Sh Ta section header (excluding standard sections)
274: .It Li \&Ss Ta subsection header
275: .It Li \&Xr Ta cross reference to another manual page
276: .It Li \&Rs Ta bibliographic reference
277: .El
278: .Pp
279: Semantic markup for command line utilities:
280: .Bl -column "xLix" description -offset indent -compact
281: .It Li \&Fl Ta command line options (flags)
282: .It Li \&Cm Ta command modifier
283: .It Li \&Ar Ta command argument
284: .It Li \&Ic Ta internal or interactive command
285: .It Li \&Ev Ta environmental variable
286: .It Li \&Pa Ta file system path
287: .El
288: .Pp
289: Semantic markup for function libraries:
290: .Bl -column "xLix" description -offset indent -compact
291: .It Li \&Lb Ta function library name
292: .It Li \&In Ta include file
293: .It Li \&Ft Ta function return type
294: .It Li \&Fn Ta function name
295: .It Li \&Fa Ta function argument type and name
296: .It Li \&Vt Ta variable type
297: .It Li \&Va Ta variable name
298: .It Li \&Dv Ta defined variable or preprocessor constant
299: .It Li \&Er Ta error constant
300: .It Li \&Ev Ta environmental variable
301: .El
302: .Pp
303: Various semantic markup:
304: .Bl -column "xLix" description -offset indent -compact
305: .It Li \&An Ta author name
306: .It Li \&Lk Ta hyperlink
307: .It Li \&Mt Ta Do mailto Dc hyperlink
308: .It Li \&Cd Ta kernel configuration declaration
309: .It Li \&Ms Ta mathematical symbol
310: .It Li \&Tn Ta tradename
311: .El
312: .Pp
313: Physical markup:
314: .Bl -column "xLix" description -offset indent -compact
315: .It Li \&Em Ta italic font or underline
316: .It Li \&Sy Ta boldface font
317: .It Li \&Li Ta typewriter font
318: .El
319: .Pp
320: Text production:
321: .Bl -column "xLix" description -offset indent -compact
322: .It Li \&St Ta reference to a standards document
323: .It Li \&At Ta At No version reference
324: .It Li \&Bx Ta Bx No version reference
325: .It Li \&Bsx Ta Bsx No version reference
326: .It Li \&Nx Ta Nx No version reference
327: .It Li \&Fx Ta Fx No version reference
328: .It Li \&Ox Ta Ox No version reference
329: .It Li \&Dx Ta Dx No version reference
1.47 ! schwarze 330: .El
! 331: .Pp
! 332: In general, macro keys are supposed to yield complete results without
! 333: expecting the user to consider actual macro usage.
! 334: For example, results include:
! 335: .Pp
! 336: .Bl -tag -width 3n -offset 3n -compact
! 337: .It Li \&Fa
! 338: function arguments appearing on
! 339: .Ic \&Fn
! 340: lines
! 341: .It Li \&Fn
! 342: fuction names marked up with
! 343: .Ic \&Fo
! 344: macros
! 345: .It Li \&In
! 346: include file names marked up with
! 347: .Ic \&Fd
! 348: macros
! 349: .It Li \&Vt
! 350: types appearing as function return types and
! 351: .It \&
! 352: types appearing in function arguments in the SYNOPSIS
1.10 kristaps 353: .El
1.6 kristaps 354: .Sh ENVIRONMENT
1.33 schwarze 355: .Bl -tag -width MANPAGER
356: .It Ev MANPAGER
357: Any non-empty value of the environment variable
358: .Ev MANPAGER
1.42 schwarze 359: is used instead of the standard pagination program,
360: .Xr more 1 ;
361: see
362: .Xr man 1
363: for details.
364: Only used if
365: .Fl a
366: or
367: .Fl l
368: is specified.
1.6 kristaps 369: .It Ev MANPATH
1.42 schwarze 370: A colon-separated list of directories to search for manual pages; see
1.23 schwarze 371: .Xr man 1
1.42 schwarze 372: for details.
1.9 schwarze 373: Overridden by
1.42 schwarze 374: .Fl M ,
375: ignored if
376: .Fl l
377: is specified.
1.33 schwarze 378: .It Ev PAGER
379: Specifies the pagination program to use when
380: .Ev MANPAGER
381: is not defined.
382: If neither PAGER nor MANPAGER is defined,
1.39 schwarze 383: .Xr more 1
384: .Fl s
1.42 schwarze 385: is used.
386: Only used if
387: .Fl a
388: or
389: .Fl l
390: is specified.
1.13 schwarze 391: .El
392: .Sh FILES
393: .Bl -tag -width "/etc/man.conf" -compact
1.22 schwarze 394: .It Pa mandoc.db
1.13 schwarze 395: name of the
1.28 schwarze 396: .Xr makewhatis 8
1.13 schwarze 397: keyword database
398: .It Pa /etc/man.conf
399: default
400: .Xr man 1
401: configuration file
1.6 kristaps 402: .El
1.1 kristaps 403: .Sh EXIT STATUS
404: .Ex -std
405: .Sh EXAMPLES
406: Search for
1.23 schwarze 407: .Qq .cf
408: as a substring of manual names and descriptions:
1.4 kristaps 409: .Pp
1.23 schwarze 410: .Dl $ apropos .cf
1.4 kristaps 411: .Pp
1.11 kristaps 412: Include matches for
1.23 schwarze 413: .Qq .cnf
1.11 kristaps 414: and
1.23 schwarze 415: .Qq .conf
416: as well:
417: .Pp
418: .Dl $ apropos .cf .cnf .conf
419: .Pp
420: Search in names and descriptions using a regular expression:
1.4 kristaps 421: .Pp
1.38 schwarze 422: .Dl $ apropos \(aq\(tiset.?[ug]id\(aq
1.4 kristaps 423: .Pp
1.27 schwarze 424: Search for manuals in the library section mentioning both the
1.23 schwarze 425: .Qq optind
426: and the
1.4 kristaps 427: .Qq optarg
1.23 schwarze 428: variables:
429: .Pp
430: .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
1.1 kristaps 431: .Pp
1.23 schwarze 432: Do exactly the same as calling
1.46 schwarze 433: .Nm whatis
1.23 schwarze 434: with the argument
435: .Qq ssh :
436: .Pp
1.38 schwarze 437: .Dl $ apropos \-\- \-i \(aqNm\(ti[[:<:]]ssh[[:>:]]\(aq
1.24 schwarze 438: .Pp
439: The following two invocations are equivalent:
440: .Pp
441: .D1 Li $ apropos -S Ar arch Li -s Ar section expression
442: .Bd -ragged -offset indent
443: .Li $ apropos \e( Ar expression Li \e)
1.38 schwarze 444: .Li -a arch\(ti^( Ns Ar arch Ns Li |any)$
445: .Li -a sec\(ti^ Ns Ar section Ns Li $
1.24 schwarze 446: .Ed
1.1 kristaps 447: .Sh SEE ALSO
1.23 schwarze 448: .Xr man 1 ,
449: .Xr re_format 7 ,
1.28 schwarze 450: .Xr makewhatis 8
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