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