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