Annotation of mandoc/apropos.1, Revision 1.20
1.20 ! schwarze 1: .\" $Id: apropos.1,v 1.19 2012/06/09 14:11:15 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.20 ! schwarze 17: .Dd $Mdocdate: June 9 2012 $
1.1 kristaps 18: .Dt APROPOS 1
19: .Os
20: .Sh NAME
1.19 kristaps 21: .Nm apropos ,
22: .Nm whatis
1.5 kristaps 23: .Nd search manual page databases
1.1 kristaps 24: .Sh SYNOPSIS
25: .Nm
1.13 schwarze 26: .Op Fl C Ar file
1.20 ! schwarze 27: .Op Fl M Ar path
! 28: .Op Fl m Ar path
1.3 kristaps 29: .Op Fl S Ar arch
30: .Op Fl s Ar section
1.13 schwarze 31: .Ar expression ...
1.1 kristaps 32: .Sh DESCRIPTION
33: The
1.19 kristaps 34: .Nm apropos
35: and
36: .Nm whatis
37: utilities query manual page databases generated by
1.8 kristaps 38: .Xr mandocdb 8 ,
1.4 kristaps 39: evaluating on
40: .Ar expression
1.5 kristaps 41: for each file in each database.
1.16 kristaps 42: .Pp
43: By default,
44: .Nm
45: searches for
46: .Xr mandocdb 8
47: databases in the default paths stipulated by
1.18 kristaps 48: .Xr man 1
49: and
1.19 kristaps 50: maps terms to case-sensitive manual names and descriptions.
1.18 kristaps 51: Multiple terms are OR'd.
1.19 kristaps 52: .Nm whatis
53: maps terms only to case-sensitive manual names.
1.16 kristaps 54: .Pp
1.1 kristaps 55: Its arguments are as follows:
56: .Bl -tag -width Ds
1.13 schwarze 57: .It Fl C Ar file
58: Specify an alternative configuration
59: .Ar file
60: in
61: .Xr man.conf 5
62: format.
1.20 ! schwarze 63: .It Fl M Ar path
1.7 kristaps 64: Use the colon-separated path instead of the default list of paths
65: searched for
66: .Xr mandocdb 8
67: databases.
68: Invalid paths, or paths without manual databases, are ignored.
1.20 ! schwarze 69: .It Fl m Ar path
1.9 schwarze 70: Prepend the colon-separated paths to the list of paths searched
1.6 kristaps 71: for
1.5 kristaps 72: .Xr mandocdb 8
73: databases.
1.6 kristaps 74: Invalid paths, or paths without manual databases, are ignored.
1.3 kristaps 75: .It Fl S Ar arch
1.1 kristaps 76: Search only for a particular architecture.
1.3 kristaps 77: .It Fl s Ar cat
78: Search only for a manual section.
1.1 kristaps 79: See
80: .Xr man 1
1.3 kristaps 81: for a listing of manual sections.
1.4 kristaps 82: .El
83: .Pp
1.19 kristaps 84: .Nm whatis
85: considers an
1.4 kristaps 86: .Ar expression
1.19 kristaps 87: to consist of an opaque keyword.
88: .Nm apropos
89: parses a
90: .Ar expression
91: into type and keyword pairs.
1.18 kristaps 92: This pair syntax
1.4 kristaps 93: .Li [key[,key]*(=~)]?val ,
94: where operand
1.10 kristaps 95: .Cm key
1.4 kristaps 96: is an
97: .Xr mdoc 7
98: macro to query and
1.10 kristaps 99: .Cm val
1.4 kristaps 100: is its value.
1.10 kristaps 101: See
102: .Sx Macro Keys
103: for a list of available keys.
1.4 kristaps 104: Operator
105: .Li \&=
1.18 kristaps 106: evaluates a full string, while
1.4 kristaps 107: .Li \&~
1.18 kristaps 108: evaluates a
109: .Xr glob 7
110: pattern.
1.1 kristaps 111: .Pp
1.4 kristaps 112: Results are sorted by manual title, with output formatted as
1.18 kristaps 113: .Qq title(sec) \- description
114: where
1.1 kristaps 115: .Qq title
116: is the manual's title (note multiple manual names may exist for one
117: title),
1.3 kristaps 118: .Qq sec
119: is the manual section, and
1.1 kristaps 120: .Qq description
121: is the manual's short description.
122: If an architecture is specified for the manual, it is displayed as
1.18 kristaps 123: .Qq title(cat/arch) \- description .
1.10 kristaps 124: .Ss Macro Keys
1.19 kristaps 125: .Nm apropos
126: queries evaluate over a subset of
1.10 kristaps 127: .Xr mdoc 7
128: macros indexed by
129: .Xr mandocdb 8 .
130: In addition to the macro keys listed below, the special key
131: .Cm any
132: may be used to match any available macro key.
133: .Pp
134: Names and description:
135: .Bl -column "xLix" description -offset indent -compact
136: .It Li \&Nm Ta manual name
137: .It Li \&Nd Ta one-line manual description
138: .El
139: .Pp
140: Sections and cross references:
141: .Bl -column "xLix" description -offset indent -compact
142: .It Li \&Sh Ta section header (excluding standard sections)
143: .It Li \&Ss Ta subsection header
144: .It Li \&Xr Ta cross reference to another manual page
145: .It Li \&Rs Ta bibliographic reference
146: .El
147: .Pp
148: Semantic markup for command line utilities:
149: .Bl -column "xLix" description -offset indent -compact
150: .It Li \&Fl Ta command line options (flags)
151: .It Li \&Cm Ta command modifier
152: .It Li \&Ar Ta command argument
153: .It Li \&Ic Ta internal or interactive command
154: .It Li \&Ev Ta environmental variable
155: .It Li \&Pa Ta file system path
156: .El
157: .Pp
158: Semantic markup for function libraries:
159: .Bl -column "xLix" description -offset indent -compact
160: .It Li \&Lb Ta function library name
161: .It Li \&In Ta include file
162: .It Li \&Ft Ta function return type
163: .It Li \&Fn Ta function name
164: .It Li \&Fa Ta function argument type and name
165: .It Li \&Vt Ta variable type
166: .It Li \&Va Ta variable name
167: .It Li \&Dv Ta defined variable or preprocessor constant
168: .It Li \&Er Ta error constant
169: .It Li \&Ev Ta environmental variable
170: .El
171: .Pp
172: Various semantic markup:
173: .Bl -column "xLix" description -offset indent -compact
174: .It Li \&An Ta author name
175: .It Li \&Lk Ta hyperlink
176: .It Li \&Mt Ta Do mailto Dc hyperlink
177: .It Li \&Cd Ta kernel configuration declaration
178: .It Li \&Ms Ta mathematical symbol
179: .It Li \&Tn Ta tradename
180: .El
181: .Pp
182: Physical markup:
183: .Bl -column "xLix" description -offset indent -compact
184: .It Li \&Em Ta italic font or underline
185: .It Li \&Sy Ta boldface font
186: .It Li \&Li Ta typewriter font
187: .El
188: .Pp
189: Text production:
190: .Bl -column "xLix" description -offset indent -compact
191: .It Li \&St Ta reference to a standards document
192: .It Li \&At Ta At No version reference
193: .It Li \&Bx Ta Bx No version reference
194: .It Li \&Bsx Ta Bsx No version reference
195: .It Li \&Nx Ta Nx No version reference
196: .It Li \&Fx Ta Fx No version reference
197: .It Li \&Ox Ta Ox No version reference
198: .It Li \&Dx Ta Dx No version reference
199: .El
1.6 kristaps 200: .Sh ENVIRONMENT
201: .Bl -tag -width Ds
202: .It Ev MANPATH
1.14 kristaps 203: Colon-separated paths modifying the default list of paths searched for
1.6 kristaps 204: manual databases.
205: Invalid paths, or paths without manual databases, are ignored.
1.9 schwarze 206: Overridden by
1.7 kristaps 207: .Fl M .
1.14 kristaps 208: If
209: .Ev MANPATH
210: begins with a
211: .Sq \&: ,
212: it is appended to the default list;
213: else if it ends with
214: .Sq \&: ,
215: it is prepended to the default list; else if it contains
216: .Sq \&:: ,
217: the default list is inserted between the colons.
218: If none of these conditions are met, it overrides the default list.
1.13 schwarze 219: .El
220: .Sh FILES
221: .Bl -tag -width "/etc/man.conf" -compact
1.19 kristaps 222: .It Pa mandocdb.db
1.13 schwarze 223: name of the
224: .Xr mandocdb 8
225: keyword database
226: .It Pa /etc/man.conf
227: default
228: .Xr man 1
229: configuration file
1.6 kristaps 230: .El
1.1 kristaps 231: .Sh EXIT STATUS
232: .Ex -std
233: .Sh EXAMPLES
234: Search for
1.4 kristaps 235: .Qq mdoc
1.18 kristaps 236: as a word or
237: .Xr glob 7
238: expression:
1.4 kristaps 239: .Pp
240: .Dl $ apropos mdoc
1.18 kristaps 241: .Dl $ apropos any~mdoc*
1.4 kristaps 242: .Pp
1.11 kristaps 243: Include matches for
244: .Qq roff
245: and
1.4 kristaps 246: .Qq man
1.18 kristaps 247: using
248: .Xr glob 7
249: expressions:
1.4 kristaps 250: .Pp
1.18 kristaps 251: .Dl $ apropos ~*mdoc* ~*roff*
1.4 kristaps 252: .Pp
253: Search for
254: .Qq optarg
1.18 kristaps 255: as a variable name in the library category:
1.1 kristaps 256: .Pp
1.18 kristaps 257: .Dl $ apropos \-s 3 Va=optarg
1.1 kristaps 258: .Sh SEE ALSO
1.18 kristaps 259: .Xr glob 7 ,
1.11 kristaps 260: .Xr mandocdb 8
1.1 kristaps 261: .Sh AUTHORS
262: The
263: .Nm
264: utility was written by
1.2 kristaps 265: .An Kristaps Dzonsons ,
266: .Mt kristaps@bsd.lv .
CVSweb