Annotation of mandoc/apropos.1, Revision 1.17
1.17 ! kristaps 1: .\" $Id: apropos.1,v 1.16 2011/12/25 19:35:44 kristaps Exp $
1.1 kristaps 2: .\"
1.17 ! kristaps 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 kristaps 17: .Dd $Mdocdate: December 25 2011 $
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.7 kristaps 26: .Op Fl M Ar manpath
1.5 kristaps 27: .Op Fl m Ar manpath
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
1.17 ! kristaps 47: over manual names and descriptions.
1.16 kristaps 48: Multiple terms imply pairwise
49: .Fl o .
1.17 ! kristaps 50: If standard output is a TTY, a result may be selected from a list and
! 51: its manual displayed with the pager.
1.16 kristaps 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.7 kristaps 61: .It Fl M Ar manpath
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.5 kristaps 67: .It Fl m Ar manpath
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
1.17 ! kristaps 159: If on a TTY, results are prefixed with a numeric identifier.
1.1 kristaps 160: .Pp
1.17 ! kristaps 161: .D1 [index] title(cat) \- description
1.1 kristaps 162: .Pp
1.17 ! kristaps 163: One may choose a manual be entering the index at the prompt.
! 164: Valid choices are displayed using
! 165: .Ev MANPAGER ,
! 166: or failing that ,
! 167: .Ev PAGER
! 168: or just
! 169: .Xr more 1 .
! 170: Source pages are formatted with
! 171: .Xr mandoc 1 ;
! 172: preformatted pages with
! 173: .Xr cat 1 .
1.10 kristaps 174: .Ss Macro Keys
175: Queries evaluate over a subset of
176: .Xr mdoc 7
177: macros indexed by
178: .Xr mandocdb 8 .
179: In addition to the macro keys listed below, the special key
180: .Cm any
181: may be used to match any available macro key.
182: .Pp
183: Names and description:
184: .Bl -column "xLix" description -offset indent -compact
185: .It Li \&Nm Ta manual name
186: .It Li \&Nd Ta one-line manual description
187: .El
188: .Pp
189: Sections and cross references:
190: .Bl -column "xLix" description -offset indent -compact
191: .It Li \&Sh Ta section header (excluding standard sections)
192: .It Li \&Ss Ta subsection header
193: .It Li \&Xr Ta cross reference to another manual page
194: .It Li \&Rs Ta bibliographic reference
195: .El
196: .Pp
197: Semantic markup for command line utilities:
198: .Bl -column "xLix" description -offset indent -compact
199: .It Li \&Fl Ta command line options (flags)
200: .It Li \&Cm Ta command modifier
201: .It Li \&Ar Ta command argument
202: .It Li \&Ic Ta internal or interactive command
203: .It Li \&Ev Ta environmental variable
204: .It Li \&Pa Ta file system path
205: .El
206: .Pp
207: Semantic markup for function libraries:
208: .Bl -column "xLix" description -offset indent -compact
209: .It Li \&Lb Ta function library name
210: .It Li \&In Ta include file
211: .It Li \&Ft Ta function return type
212: .It Li \&Fn Ta function name
213: .It Li \&Fa Ta function argument type and name
214: .It Li \&Vt Ta variable type
215: .It Li \&Va Ta variable name
216: .It Li \&Dv Ta defined variable or preprocessor constant
217: .It Li \&Er Ta error constant
218: .It Li \&Ev Ta environmental variable
219: .El
220: .Pp
221: Various semantic markup:
222: .Bl -column "xLix" description -offset indent -compact
223: .It Li \&An Ta author name
224: .It Li \&Lk Ta hyperlink
225: .It Li \&Mt Ta Do mailto Dc hyperlink
226: .It Li \&Cd Ta kernel configuration declaration
227: .It Li \&Ms Ta mathematical symbol
228: .It Li \&Tn Ta tradename
229: .El
230: .Pp
231: Physical markup:
232: .Bl -column "xLix" description -offset indent -compact
233: .It Li \&Em Ta italic font or underline
234: .It Li \&Sy Ta boldface font
235: .It Li \&Li Ta typewriter font
236: .El
237: .Pp
238: Text production:
239: .Bl -column "xLix" description -offset indent -compact
240: .It Li \&St Ta reference to a standards document
241: .It Li \&At Ta At No version reference
242: .It Li \&Bx Ta Bx No version reference
243: .It Li \&Bsx Ta Bsx No version reference
244: .It Li \&Nx Ta Nx No version reference
245: .It Li \&Fx Ta Fx No version reference
246: .It Li \&Ox Ta Ox No version reference
247: .It Li \&Dx Ta Dx No version reference
248: .El
1.6 kristaps 249: .Sh ENVIRONMENT
250: .Bl -tag -width Ds
1.17 ! kristaps 251: .It Ev MANPAGER
! 252: Default pager for manuals.
! 253: If this is unset, falls back to
! 254: .Ev Pager .
! 255: .It Ev PAGER
! 256: The second choice for a manual pager.
! 257: If this is unset, use
! 258: .Xr more 1 .
1.6 kristaps 259: .It Ev MANPATH
1.14 kristaps 260: Colon-separated paths modifying the default list of paths searched for
1.6 kristaps 261: manual databases.
262: Invalid paths, or paths without manual databases, are ignored.
1.9 schwarze 263: Overridden by
1.7 kristaps 264: .Fl M .
1.14 kristaps 265: If
266: .Ev MANPATH
267: begins with a
268: .Sq \&: ,
269: it is appended to the default list;
270: else if it ends with
271: .Sq \&: ,
272: it is prepended to the default list; else if it contains
273: .Sq \&:: ,
274: the default list is inserted between the colons.
275: If none of these conditions are met, it overrides the default list.
1.13 schwarze 276: .El
277: .Sh FILES
278: .Bl -tag -width "/etc/man.conf" -compact
1.15 schwarze 279: .It Pa whatis.db
1.13 schwarze 280: name of the
281: .Xr mandocdb 8
282: keyword database
1.15 schwarze 283: .It Pa whatis.index
1.13 schwarze 284: name of the
285: .Xr mandocdb 8
286: filename database
287: .It Pa /etc/man.conf
288: default
289: .Xr man 1
290: configuration file
1.6 kristaps 291: .El
1.1 kristaps 292: .Sh EXIT STATUS
293: .Ex -std
294: .Sh EXAMPLES
295: Search for
1.4 kristaps 296: .Qq mdoc
1.12 kristaps 297: as a substring and regular expression
1.11 kristaps 298: within each manual name and description:
1.4 kristaps 299: .Pp
300: .Dl $ apropos mdoc
1.11 kristaps 301: .Dl $ apropos ~^mdoc$
1.4 kristaps 302: .Pp
1.11 kristaps 303: Include matches for
304: .Qq roff
305: and
1.4 kristaps 306: .Qq man
1.11 kristaps 307: for the regular expression case:
1.4 kristaps 308: .Pp
1.11 kristaps 309: .Dl $ apropos ~^mdoc$ roff man
310: .Dl $ apropos ~^mdoc$ \-o roff \-o man
1.4 kristaps 311: .Pp
312: Search for
1.1 kristaps 313: .Qq optind
1.4 kristaps 314: and
315: .Qq optarg
316: as variable names in the library category:
1.1 kristaps 317: .Pp
1.11 kristaps 318: .Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$
1.1 kristaps 319: .Sh SEE ALSO
1.17 ! kristaps 320: .Xr more 1
1.11 kristaps 321: .Xr re_format 7 ,
322: .Xr mandocdb 8
1.1 kristaps 323: .Sh AUTHORS
324: The
325: .Nm
326: utility was written by
1.2 kristaps 327: .An Kristaps Dzonsons ,
328: .Mt kristaps@bsd.lv .
CVSweb