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