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