Annotation of mandoc/apropos.1, Revision 1.16.2.3
1.16.2.3! schwarze 1: .\" $Id: apropos.1,v 1.16.2.2 2013/09/17 20:42:09 schwarze Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
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.3! schwarze 17: .Dd $Mdocdate: September 17 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.1 kristaps 74: Search only for a particular architecture.
1.3 kristaps 75: .It Fl s Ar cat
76: Search only for a manual section.
1.1 kristaps 77: See
78: .Xr man 1
1.3 kristaps 79: for a listing of manual sections.
1.4 kristaps 80: .El
81: .Pp
82: An
83: .Ar expression
84: consists of search terms joined by logical operators
85: .Fl a
86: .Pq and
87: and
88: .Fl o
89: .Pq or .
90: The
91: .Fl a
92: operator has precedence over
93: .Fl o
94: and both are evaluated left-to-right.
95: .Bl -tag -width Ds
96: .It \&( Ar expr No \&)
97: True if the subexpression
98: .Ar expr
99: is true.
100: .It Ar expr1 Fl a Ar expr2
101: True if both
102: .Ar expr1
103: and
104: .Ar expr2
105: are true (logical
106: .Qq and ) .
107: .It Ar expr1 Oo Fl o Oc Ar expr2
108: True if
109: .Ar expr1
110: and/or
111: .Ar expr2
112: evaluate to true (logical
113: .Qq or ) .
114: .It Ar term
115: True if
116: .Ar term
117: is satisfied.
118: This has syntax
119: .Li [key[,key]*(=~)]?val ,
120: where operand
1.10 kristaps 121: .Cm key
1.4 kristaps 122: is an
123: .Xr mdoc 7
124: macro to query and
1.10 kristaps 125: .Cm val
1.4 kristaps 126: is its value.
1.10 kristaps 127: See
128: .Sx Macro Keys
129: for a list of available keys.
1.4 kristaps 130: Operator
131: .Li \&=
132: evaluates a substring, while
133: .Li \&~
134: evaluates a regular expression.
135: .It Fl i Ar term
1.11 kristaps 136: If
1.4 kristaps 137: .Ar term
1.11 kristaps 138: is a regular expression, it
1.4 kristaps 139: is evaluated case-insensitively.
1.11 kristaps 140: Has no effect on substring terms.
1.1 kristaps 141: .El
142: .Pp
1.4 kristaps 143: Results are sorted by manual title, with output formatted as
1.1 kristaps 144: .Pp
1.3 kristaps 145: .D1 title(sec) \- description
1.1 kristaps 146: .Pp
147: Where
148: .Qq title
149: is the manual's title (note multiple manual names may exist for one
150: title),
1.3 kristaps 151: .Qq sec
152: is the manual section, and
1.1 kristaps 153: .Qq description
154: is the manual's short description.
155: If an architecture is specified for the manual, it is displayed as
156: .Pp
157: .D1 title(cat/arch) \- description
158: .Pp
159: Resulting manuals may be accessed as
160: .Pp
1.3 kristaps 161: .Dl $ man \-s sec title
1.1 kristaps 162: .Pp
163: If an architecture is specified in the output, use
164: .Pp
1.3 kristaps 165: .Dl $ man \-s sec \-S arch title
1.10 kristaps 166: .Ss Macro Keys
167: Queries evaluate over a subset of
168: .Xr mdoc 7
169: macros indexed by
170: .Xr mandocdb 8 .
171: In addition to the macro keys listed below, the special key
172: .Cm any
173: may be used to match any available macro key.
174: .Pp
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
179: .El
180: .Pp
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
187: .El
188: .Pp
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
197: .El
198: .Pp
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
211: .El
212: .Pp
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
221: .El
222: .Pp
223: Physical markup:
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
228: .El
229: .Pp
230: Text production:
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
240: .El
1.6 kristaps 241: .Sh ENVIRONMENT
242: .Bl -tag -width Ds
243: .It Ev MANPATH
1.14 kristaps 244: Colon-separated paths modifying the default list of paths searched for
1.6 kristaps 245: manual databases.
246: Invalid paths, or paths without manual databases, are ignored.
1.9 schwarze 247: Overridden by
1.7 kristaps 248: .Fl M .
1.14 kristaps 249: If
250: .Ev MANPATH
251: begins with a
252: .Sq \&: ,
253: it is appended to the default list;
254: else if it ends with
255: .Sq \&: ,
256: it is prepended to the default list; else if it contains
257: .Sq \&:: ,
258: the default list is inserted between the colons.
259: If none of these conditions are met, it overrides the default list.
1.13 schwarze 260: .El
261: .Sh FILES
262: .Bl -tag -width "/etc/man.conf" -compact
1.16.2.3! schwarze 263: .It Pa mandoc.db
1.13 schwarze 264: name of the
265: .Xr mandocdb 8
266: keyword database
1.16.2.3! schwarze 267: .It Pa mandoc.index
1.13 schwarze 268: name of the
269: .Xr mandocdb 8
270: filename database
271: .It Pa /etc/man.conf
272: default
273: .Xr man 1
274: configuration file
1.6 kristaps 275: .El
1.1 kristaps 276: .Sh EXIT STATUS
277: .Ex -std
278: .Sh EXAMPLES
279: Search for
1.4 kristaps 280: .Qq mdoc
1.12 kristaps 281: as a substring and regular expression
1.11 kristaps 282: within each manual name and description:
1.4 kristaps 283: .Pp
284: .Dl $ apropos mdoc
1.11 kristaps 285: .Dl $ apropos ~^mdoc$
1.4 kristaps 286: .Pp
1.11 kristaps 287: Include matches for
288: .Qq roff
289: and
1.4 kristaps 290: .Qq man
1.11 kristaps 291: for the regular expression case:
1.4 kristaps 292: .Pp
1.11 kristaps 293: .Dl $ apropos ~^mdoc$ roff man
294: .Dl $ apropos ~^mdoc$ \-o roff \-o man
1.4 kristaps 295: .Pp
296: Search for
1.1 kristaps 297: .Qq optind
1.4 kristaps 298: and
299: .Qq optarg
300: as variable names in the library category:
1.1 kristaps 301: .Pp
1.11 kristaps 302: .Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$
1.1 kristaps 303: .Sh SEE ALSO
304: .Xr man 1 ,
1.11 kristaps 305: .Xr re_format 7 ,
306: .Xr mandocdb 8
1.1 kristaps 307: .Sh AUTHORS
308: The
309: .Nm
310: utility was written by
1.16.2.2 schwarze 311: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
CVSweb