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