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