1 .\" $Id: apropos.1,v 1.16 2011/12/25 19:35:44 kristaps Exp $
3 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
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.
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.
17 .Dd $Mdocdate: December 25 2011 $
22 .Nd search manual page databases
34 utility queries manual page databases generated by
38 for each file in each database.
44 databases in the default paths stipulated by
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
53 Its arguments are as follows:
56 Specify an alternative configuration
62 Use the colon-separated path instead of the default list of paths
66 Invalid paths, or paths without manual databases, are ignored.
68 Prepend the colon-separated paths to the list of paths searched
72 Invalid paths, or paths without manual databases, are ignored.
74 Search only for a particular architecture.
76 Search only for a manual section.
79 for a listing of manual sections.
84 consists of search terms joined by logical operators
92 operator has precedence over
94 and both are evaluated left-to-right.
96 .It \&( Ar expr No \&)
97 True if the subexpression
100 .It Ar expr1 Fl a Ar expr2
107 .It Ar expr1 Oo Fl o Oc Ar expr2
112 evaluate to true (logical
119 .Li [key[,key]*(=~)]?val ,
129 for a list of available keys.
132 evaluates a substring, while
134 evaluates a regular expression.
138 is a regular expression, it
139 is evaluated case-insensitively.
140 Has no effect on substring terms.
143 Results are sorted by manual title, with output formatted as
145 .D1 title(sec) \- description
149 is the manual's title (note multiple manual names may exist for one
152 is the manual section, and
154 is the manual's short description.
155 If an architecture is specified for the manual, it is displayed as
157 .D1 title(cat/arch) \- description
159 Resulting manuals may be accessed as
161 .Dl $ man \-s sec title
163 If an architecture is specified in the output, use
165 .Dl $ man \-s sec \-S arch title
167 Queries evaluate over a subset of
171 In addition to the macro keys listed below, the special key
173 may be used to match any available macro key.
175 Names and description:
176 .Bl -column "xLix" description -offset indent -compact
177 .It Li \&Nm Ta manual name
178 .It Li \&Nd Ta one-line manual description
181 Sections and cross references:
182 .Bl -column "xLix" description -offset indent -compact
183 .It Li \&Sh Ta section header (excluding standard sections)
184 .It Li \&Ss Ta subsection header
185 .It Li \&Xr Ta cross reference to another manual page
186 .It Li \&Rs Ta bibliographic reference
189 Semantic markup for command line utilities:
190 .Bl -column "xLix" description -offset indent -compact
191 .It Li \&Fl Ta command line options (flags)
192 .It Li \&Cm Ta command modifier
193 .It Li \&Ar Ta command argument
194 .It Li \&Ic Ta internal or interactive command
195 .It Li \&Ev Ta environmental variable
196 .It Li \&Pa Ta file system path
199 Semantic markup for function libraries:
200 .Bl -column "xLix" description -offset indent -compact
201 .It Li \&Lb Ta function library name
202 .It Li \&In Ta include file
203 .It Li \&Ft Ta function return type
204 .It Li \&Fn Ta function name
205 .It Li \&Fa Ta function argument type and name
206 .It Li \&Vt Ta variable type
207 .It Li \&Va Ta variable name
208 .It Li \&Dv Ta defined variable or preprocessor constant
209 .It Li \&Er Ta error constant
210 .It Li \&Ev Ta environmental variable
213 Various semantic markup:
214 .Bl -column "xLix" description -offset indent -compact
215 .It Li \&An Ta author name
216 .It Li \&Lk Ta hyperlink
217 .It Li \&Mt Ta Do mailto Dc hyperlink
218 .It Li \&Cd Ta kernel configuration declaration
219 .It Li \&Ms Ta mathematical symbol
220 .It Li \&Tn Ta tradename
224 .Bl -column "xLix" description -offset indent -compact
225 .It Li \&Em Ta italic font or underline
226 .It Li \&Sy Ta boldface font
227 .It Li \&Li Ta typewriter font
231 .Bl -column "xLix" description -offset indent -compact
232 .It Li \&St Ta reference to a standards document
233 .It Li \&At Ta At No version reference
234 .It Li \&Bx Ta Bx No version reference
235 .It Li \&Bsx Ta Bsx No version reference
236 .It Li \&Nx Ta Nx No version reference
237 .It Li \&Fx Ta Fx No version reference
238 .It Li \&Ox Ta Ox No version reference
239 .It Li \&Dx Ta Dx No version reference
244 Colon-separated paths modifying the default list of paths searched for
246 Invalid paths, or paths without manual databases, are ignored.
253 it is appended to the default list;
256 it is prepended to the default list; else if it contains
258 the default list is inserted between the colons.
259 If none of these conditions are met, it overrides the default list.
262 .Bl -tag -width "/etc/man.conf" -compact
281 as a substring and regular expression
282 within each manual name and description:
285 .Dl $ apropos ~^mdoc$
291 for the regular expression case:
293 .Dl $ apropos ~^mdoc$ roff man
294 .Dl $ apropos ~^mdoc$ \-o roff \-o man
300 as variable names in the library category:
302 .Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$
310 utility was written by
311 .An Kristaps Dzonsons ,
312 .Mt kristaps@bsd.lv .