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