Annotation of mandoc/apropos.1, Revision 1.13
1.13 ! schwarze 1: .\" $Id: apropos.1,v 1.12 2011/11/29 10:59:19 kristaps 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.11 kristaps 17: .Dd $Mdocdate: November 29 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.1 kristaps 39: Its arguments are as follows:
40: .Bl -tag -width Ds
1.13 ! schwarze 41: .It Fl C Ar file
! 42: Specify an alternative configuration
! 43: .Ar file
! 44: in
! 45: .Xr man.conf 5
! 46: format.
1.7 kristaps 47: .It Fl M Ar manpath
48: Use the colon-separated path instead of the default list of paths
49: searched for
50: .Xr mandocdb 8
51: databases.
52: Invalid paths, or paths without manual databases, are ignored.
1.5 kristaps 53: .It Fl m Ar manpath
1.9 schwarze 54: Prepend the colon-separated paths to the list of paths searched
1.6 kristaps 55: for
1.5 kristaps 56: .Xr mandocdb 8
57: databases.
1.6 kristaps 58: Invalid paths, or paths without manual databases, are ignored.
1.3 kristaps 59: .It Fl S Ar arch
1.1 kristaps 60: Search only for a particular architecture.
1.3 kristaps 61: .It Fl s Ar cat
62: Search only for a manual section.
1.1 kristaps 63: See
64: .Xr man 1
1.3 kristaps 65: for a listing of manual sections.
1.4 kristaps 66: .El
67: .Pp
68: An
69: .Ar expression
70: consists of search terms joined by logical operators
71: .Fl a
72: .Pq and
73: and
74: .Fl o
75: .Pq or .
76: The
77: .Fl a
78: operator has precedence over
79: .Fl o
80: and both are evaluated left-to-right.
81: .Bl -tag -width Ds
82: .It \&( Ar expr No \&)
83: True if the subexpression
84: .Ar expr
85: is true.
86: .It Ar expr1 Fl a Ar expr2
87: True if both
88: .Ar expr1
89: and
90: .Ar expr2
91: are true (logical
92: .Qq and ) .
93: .It Ar expr1 Oo Fl o Oc Ar expr2
94: True if
95: .Ar expr1
96: and/or
97: .Ar expr2
98: evaluate to true (logical
99: .Qq or ) .
100: .It Ar term
101: True if
102: .Ar term
103: is satisfied.
104: This has syntax
105: .Li [key[,key]*(=~)]?val ,
106: where operand
1.10 kristaps 107: .Cm key
1.4 kristaps 108: is an
109: .Xr mdoc 7
110: macro to query and
1.10 kristaps 111: .Cm val
1.4 kristaps 112: is its value.
1.10 kristaps 113: See
114: .Sx Macro Keys
115: for a list of available keys.
1.4 kristaps 116: Operator
117: .Li \&=
118: evaluates a substring, while
119: .Li \&~
120: evaluates a regular expression.
121: .It Fl i Ar term
1.11 kristaps 122: If
1.4 kristaps 123: .Ar term
1.11 kristaps 124: is a regular expression, it
1.4 kristaps 125: is evaluated case-insensitively.
1.11 kristaps 126: Has no effect on substring terms.
1.1 kristaps 127: .El
128: .Pp
129: By default,
130: .Nm
1.7 kristaps 131: searches for
1.5 kristaps 132: .Xr mandocdb 8
1.7 kristaps 133: databases in the default paths stipulated by
134: .Xr man 1 ,
1.11 kristaps 135: parses terms as case-sensitive regular expressions
1.4 kristaps 136: .Pq the Li \&~ operator
137: over manual names and descriptions
1.10 kristaps 138: .Pq the Li \&Nm No and Li \&Nd No macro keys .
1.4 kristaps 139: Multiple terms imply pairwise
140: .Fl o .
141: Results are sorted by manual title, with output formatted as
1.1 kristaps 142: .Pp
1.3 kristaps 143: .D1 title(sec) \- description
1.1 kristaps 144: .Pp
145: Where
146: .Qq title
147: is the manual's title (note multiple manual names may exist for one
148: title),
1.3 kristaps 149: .Qq sec
150: is the manual section, and
1.1 kristaps 151: .Qq description
152: is the manual's short description.
153: If an architecture is specified for the manual, it is displayed as
154: .Pp
155: .D1 title(cat/arch) \- description
156: .Pp
157: Resulting manuals may be accessed as
158: .Pp
1.3 kristaps 159: .Dl $ man \-s sec title
1.1 kristaps 160: .Pp
161: If an architecture is specified in the output, use
162: .Pp
1.3 kristaps 163: .Dl $ man \-s sec \-S arch title
1.10 kristaps 164: .Ss Macro Keys
165: Queries evaluate over a subset of
166: .Xr mdoc 7
167: macros indexed by
168: .Xr mandocdb 8 .
169: In addition to the macro keys listed below, the special key
170: .Cm any
171: may be used to match any available macro key.
172: .Pp
173: Names and description:
174: .Bl -column "xLix" description -offset indent -compact
175: .It Li \&Nm Ta manual name
176: .It Li \&Nd Ta one-line manual description
177: .El
178: .Pp
179: Sections and cross references:
180: .Bl -column "xLix" description -offset indent -compact
181: .It Li \&Sh Ta section header (excluding standard sections)
182: .It Li \&Ss Ta subsection header
183: .It Li \&Xr Ta cross reference to another manual page
184: .It Li \&Rs Ta bibliographic reference
185: .El
186: .Pp
187: Semantic markup for command line utilities:
188: .Bl -column "xLix" description -offset indent -compact
189: .It Li \&Fl Ta command line options (flags)
190: .It Li \&Cm Ta command modifier
191: .It Li \&Ar Ta command argument
192: .It Li \&Ic Ta internal or interactive command
193: .It Li \&Ev Ta environmental variable
194: .It Li \&Pa Ta file system path
195: .El
196: .Pp
197: Semantic markup for function libraries:
198: .Bl -column "xLix" description -offset indent -compact
199: .It Li \&Lb Ta function library name
200: .It Li \&In Ta include file
201: .It Li \&Ft Ta function return type
202: .It Li \&Fn Ta function name
203: .It Li \&Fa Ta function argument type and name
204: .It Li \&Vt Ta variable type
205: .It Li \&Va Ta variable name
206: .It Li \&Dv Ta defined variable or preprocessor constant
207: .It Li \&Er Ta error constant
208: .It Li \&Ev Ta environmental variable
209: .El
210: .Pp
211: Various semantic markup:
212: .Bl -column "xLix" description -offset indent -compact
213: .It Li \&An Ta author name
214: .It Li \&Lk Ta hyperlink
215: .It Li \&Mt Ta Do mailto Dc hyperlink
216: .It Li \&Cd Ta kernel configuration declaration
217: .It Li \&Ms Ta mathematical symbol
218: .It Li \&Tn Ta tradename
219: .El
220: .Pp
221: Physical markup:
222: .Bl -column "xLix" description -offset indent -compact
223: .It Li \&Em Ta italic font or underline
224: .It Li \&Sy Ta boldface font
225: .It Li \&Li Ta typewriter font
226: .El
227: .Pp
228: Text production:
229: .Bl -column "xLix" description -offset indent -compact
230: .It Li \&St Ta reference to a standards document
231: .It Li \&At Ta At No version reference
232: .It Li \&Bx Ta Bx No version reference
233: .It Li \&Bsx Ta Bsx No version reference
234: .It Li \&Nx Ta Nx No version reference
235: .It Li \&Fx Ta Fx No version reference
236: .It Li \&Ox Ta Ox No version reference
237: .It Li \&Dx Ta Dx No version reference
238: .El
1.6 kristaps 239: .Sh ENVIRONMENT
240: .Bl -tag -width Ds
241: .It Ev MANPATH
1.9 schwarze 242: Colon-separated paths overriding the default list of paths searched for
1.6 kristaps 243: manual databases.
244: Invalid paths, or paths without manual databases, are ignored.
1.9 schwarze 245: Overridden by
1.7 kristaps 246: .Fl M .
1.13 ! schwarze 247: .El
! 248: .Sh FILES
! 249: .Bl -tag -width "/etc/man.conf" -compact
! 250: .It Pa mandoc.db
! 251: name of the
! 252: .Xr mandocdb 8
! 253: keyword database
! 254: .It Pa mandoc.index
! 255: name of the
! 256: .Xr mandocdb 8
! 257: filename database
! 258: .It Pa /etc/man.conf
! 259: default
! 260: .Xr man 1
! 261: configuration file
1.6 kristaps 262: .El
1.1 kristaps 263: .Sh EXIT STATUS
264: .Ex -std
265: .Sh EXAMPLES
266: Search for
1.4 kristaps 267: .Qq mdoc
1.12 kristaps 268: as a substring and regular expression
1.11 kristaps 269: within each manual name and description:
1.4 kristaps 270: .Pp
271: .Dl $ apropos mdoc
1.11 kristaps 272: .Dl $ apropos ~^mdoc$
1.4 kristaps 273: .Pp
1.11 kristaps 274: Include matches for
275: .Qq roff
276: and
1.4 kristaps 277: .Qq man
1.11 kristaps 278: for the regular expression case:
1.4 kristaps 279: .Pp
1.11 kristaps 280: .Dl $ apropos ~^mdoc$ roff man
281: .Dl $ apropos ~^mdoc$ \-o roff \-o man
1.4 kristaps 282: .Pp
283: Search for
1.1 kristaps 284: .Qq optind
1.4 kristaps 285: and
286: .Qq optarg
287: as variable names in the library category:
1.1 kristaps 288: .Pp
1.11 kristaps 289: .Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$
1.1 kristaps 290: .Sh SEE ALSO
291: .Xr man 1 ,
1.11 kristaps 292: .Xr re_format 7 ,
293: .Xr mandocdb 8
1.1 kristaps 294: .Sh AUTHORS
295: The
296: .Nm
297: utility was written by
1.2 kristaps 298: .An Kristaps Dzonsons ,
299: .Mt kristaps@bsd.lv .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to apropos.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc