Annotation of src/usr.bin/mandoc/apropos.1, Revision 1.21
1.21 ! schwarze 1: .\" $Id: apropos.1,v 1.20 2014/03/17 11:29:11 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.20 schwarze 18: .Dd $Mdocdate: March 17 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
1.21 ! schwarze 189: .It Li NAME Ta manual name in the NAME section, subset of \&Nm
1.7 schwarze 190: .It Li \&Nm Ta manual name
191: .It Li \&Nd Ta one-line manual description
1.20 schwarze 192: .It Li arch Ta machine architecture (case-insensitive)
193: .It Li sec Ta manual section number
1.7 schwarze 194: .El
195: .Pp
196: Sections and cross references:
197: .Bl -column "xLix" description -offset indent -compact
198: .It Li \&Sh Ta section header (excluding standard sections)
199: .It Li \&Ss Ta subsection header
200: .It Li \&Xr Ta cross reference to another manual page
201: .It Li \&Rs Ta bibliographic reference
202: .El
203: .Pp
204: Semantic markup for command line utilities:
205: .Bl -column "xLix" description -offset indent -compact
206: .It Li \&Fl Ta command line options (flags)
207: .It Li \&Cm Ta command modifier
208: .It Li \&Ar Ta command argument
209: .It Li \&Ic Ta internal or interactive command
210: .It Li \&Ev Ta environmental variable
211: .It Li \&Pa Ta file system path
212: .El
213: .Pp
214: Semantic markup for function libraries:
215: .Bl -column "xLix" description -offset indent -compact
216: .It Li \&Lb Ta function library name
217: .It Li \&In Ta include file
218: .It Li \&Ft Ta function return type
219: .It Li \&Fn Ta function name
220: .It Li \&Fa Ta function argument type and name
221: .It Li \&Vt Ta variable type
222: .It Li \&Va Ta variable name
223: .It Li \&Dv Ta defined variable or preprocessor constant
224: .It Li \&Er Ta error constant
225: .It Li \&Ev Ta environmental variable
226: .El
227: .Pp
228: Various semantic markup:
229: .Bl -column "xLix" description -offset indent -compact
230: .It Li \&An Ta author name
231: .It Li \&Lk Ta hyperlink
232: .It Li \&Mt Ta Do mailto Dc hyperlink
233: .It Li \&Cd Ta kernel configuration declaration
234: .It Li \&Ms Ta mathematical symbol
235: .It Li \&Tn Ta tradename
236: .El
237: .Pp
238: Physical markup:
239: .Bl -column "xLix" description -offset indent -compact
240: .It Li \&Em Ta italic font or underline
241: .It Li \&Sy Ta boldface font
242: .It Li \&Li Ta typewriter font
243: .El
244: .Pp
245: Text production:
246: .Bl -column "xLix" description -offset indent -compact
247: .It Li \&St Ta reference to a standards document
248: .It Li \&At Ta At No version reference
249: .It Li \&Bx Ta Bx No version reference
250: .It Li \&Bsx Ta Bsx No version reference
251: .It Li \&Nx Ta Nx No version reference
252: .It Li \&Fx Ta Fx No version reference
253: .It Li \&Ox Ta Ox No version reference
254: .It Li \&Dx Ta Dx No version reference
255: .El
1.6 schwarze 256: .Sh ENVIRONMENT
1.13 schwarze 257: .Bl -tag -width MANPATH
1.6 schwarze 258: .It Ev MANPATH
1.13 schwarze 259: The standard search path used by
260: .Xr man 1
261: may be changed by specifying a path in the
262: .Ev MANPATH
263: environment variable.
1.6 schwarze 264: Invalid paths, or paths without manual databases, are ignored.
265: Overridden by
266: .Fl M .
1.10 schwarze 267: If
268: .Ev MANPATH
1.13 schwarze 269: begins with a colon, it is appended to the default list;
270: if it ends with a colon, it is prepended to the default list;
271: or if it contains two adjacent colons,
272: the standard search path is inserted between the colons.
273: If none of these conditions are met, it overrides the
274: standard search path.
1.9 schwarze 275: .El
276: .Sh FILES
277: .Bl -tag -width "/etc/man.conf" -compact
1.15 schwarze 278: .It Pa mandoc.db
1.9 schwarze 279: name of the
1.16 schwarze 280: .Xr makewhatis 8
1.9 schwarze 281: keyword database
282: .It Pa /etc/man.conf
283: default
284: .Xr man 1
285: configuration file
1.6 schwarze 286: .El
1.1 schwarze 287: .Sh EXIT STATUS
288: .Ex -std
289: .Sh EXAMPLES
290: Search for
1.14 schwarze 291: .Qq .cf
292: as a substring of manual names and descriptions:
1.4 schwarze 293: .Pp
1.14 schwarze 294: .Dl $ apropos .cf
1.4 schwarze 295: .Pp
1.8 schwarze 296: Include matches for
1.14 schwarze 297: .Qq .cnf
1.8 schwarze 298: and
1.14 schwarze 299: .Qq .conf
300: as well:
1.4 schwarze 301: .Pp
1.14 schwarze 302: .Dl $ apropos .cf .cnf .conf
1.4 schwarze 303: .Pp
1.14 schwarze 304: Search in names and descriptions using a regular expression:
305: .Pp
306: .Dl $ apropos '~set.?[ug]id'
307: .Pp
308: Search for manuals in the library category mentioning both the
1.1 schwarze 309: .Qq optind
1.14 schwarze 310: and the
1.4 schwarze 311: .Qq optarg
1.14 schwarze 312: variables:
313: .Pp
314: .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
315: .Pp
316: Do exactly the same as calling
317: .Xr whatis 1
318: with the argument
319: .Qq ssh :
1.1 schwarze 320: .Pp
1.14 schwarze 321: .Dl $ apropos \-\- \-i 'Nm~[[:<:]]ssh[[:>:]]'
1.20 schwarze 322: .Pp
323: The following two invocations are equivalent:
324: .Pp
325: .D1 Li $ apropos -S Ar arch Li -s Ar section expression
326: .Bd -ragged -offset indent
327: .Li $ apropos \e( Ar expression Li \e)
328: .Li -a arch~^( Ns Ar arch Ns Li |any)$
329: .Li -a sec~^ Ns Ar section Ns Li $
330: .Ed
1.1 schwarze 331: .Sh SEE ALSO
332: .Xr man 1 ,
1.8 schwarze 333: .Xr re_format 7 ,
1.16 schwarze 334: .Xr makewhatis 8
1.17 schwarze 335: .Sh HISTORY
336: An
337: .Nm
338: utility first appeared in
339: .Bx 2 .
340: It was rewritten from scratch for
1.20 schwarze 341: .Ox 5.6 .
1.17 schwarze 342: .Pp
343: The
344: .Fl M
345: option and the
346: .Ev MANPATH
347: variable first appeared in
348: .Bx 4.3 ;
349: .Fl m
350: in
351: .Bx 4.3 Reno ;
352: .Fl C
353: in
354: .Bx 4.4 Lite1 ;
355: and
356: .Fl S
357: and
358: .Fl s
359: in
360: .Ox 4.5 .
1.1 schwarze 361: .Sh AUTHORS
1.17 schwarze 362: .An -nosplit
363: .An Bill Joy
364: wrote the original
365: .Bx
1.1 schwarze 366: .Nm
1.17 schwarze 367: in February 1979.
368: The current version was written by
1.20 schwarze 369: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
370: and
371: .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