Annotation of mandoc/apropos.1, Revision 1.7
1.7 ! kristaps 1: .\" $Id: apropos.1,v 1.6 2011/11/20 16:29:50 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.6 kristaps 17: .Dd $Mdocdate: November 20 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.7 ! kristaps 25: .Op Fl M Ar manpath
1.5 kristaps 26: .Op Fl m Ar manpath
1.3 kristaps 27: .Op Fl S Ar arch
28: .Op Fl s Ar section
1.4 kristaps 29: .Ar expression...
1.1 kristaps 30: .Sh DESCRIPTION
31: The
32: .Nm
1.5 kristaps 33: utility queries manual page databases generated by
1.4 kristaps 34: .Xr mandocdb 8 ,
35: evaluating on
36: .Ar expression
1.5 kristaps 37: for each file in each database.
1.1 kristaps 38: Its arguments are as follows:
39: .Bl -tag -width Ds
1.7 ! kristaps 40: .It Fl M Ar manpath
! 41: Use the colon-separated path instead of the default list of paths
! 42: searched for
! 43: .Xr mandocdb 8
! 44: databases.
! 45: Invalid paths, or paths without manual databases, are ignored.
1.5 kristaps 46: .It Fl m Ar manpath
1.7 ! kristaps 47: Append the colon-separated paths to the list of paths searched
1.6 kristaps 48: for
1.5 kristaps 49: .Xr mandocdb 8
50: databases.
1.6 kristaps 51: Invalid paths, or paths without manual databases, are ignored.
1.3 kristaps 52: .It Fl S Ar arch
1.1 kristaps 53: Search only for a particular architecture.
1.3 kristaps 54: .It Fl s Ar cat
55: Search only for a manual section.
1.1 kristaps 56: See
57: .Xr man 1
1.3 kristaps 58: for a listing of manual sections.
1.4 kristaps 59: .El
60: .Pp
61: An
62: .Ar expression
63: consists of search terms joined by logical operators
64: .Fl a
65: .Pq and
66: and
67: .Fl o
68: .Pq or .
69: The
70: .Fl a
71: operator has precedence over
72: .Fl o
73: and both are evaluated left-to-right.
74: .Pp
75: .Bl -tag -width Ds
76: .It \&( Ar expr No \&)
77: True if the subexpression
78: .Ar expr
79: is true.
80: .It Ar expr1 Fl a Ar expr2
81: True if both
82: .Ar expr1
83: and
84: .Ar expr2
85: are true (logical
86: .Qq and ) .
87: .It Ar expr1 Oo Fl o Oc Ar expr2
88: True if
89: .Ar expr1
90: and/or
91: .Ar expr2
92: evaluate to true (logical
93: .Qq or ) .
94: .It Ar term
95: True if
96: .Ar term
97: is satisfied.
98: This has syntax
99: .Li [key[,key]*(=~)]?val ,
100: where operand
101: .Li key
102: is an
103: .Xr mdoc 7
104: macro to query and
105: .Li val
106: is its value.
107: Operator
108: .Li \&=
109: evaluates a substring, while
110: .Li \&~
111: evaluates a regular expression.
112: .It Fl i Ar term
113: Same as
114: .Ar term ,
115: but
116: .Ar term
117: is evaluated case-insensitively.
1.1 kristaps 118: .El
119: .Pp
120: By default,
121: .Nm
1.7 ! kristaps 122: searches for
1.5 kristaps 123: .Xr mandocdb 8
1.7 ! kristaps 124: databases in the default paths stipulated by
! 125: .Xr man 1 ,
1.4 kristaps 126: parses terms as case-sensitive regular expressions
127: .Pq the Li \&~ operator
128: over manual names and descriptions
129: .Pq the Li \&Nm No and Li \&Nd No macros .
130: Multiple terms imply pairwise
131: .Fl o .
132: Results are sorted by manual title, with output formatted as
1.1 kristaps 133: .Pp
1.3 kristaps 134: .D1 title(sec) \- description
1.1 kristaps 135: .Pp
136: Where
137: .Qq title
138: is the manual's title (note multiple manual names may exist for one
139: title),
1.3 kristaps 140: .Qq sec
141: is the manual section, and
1.1 kristaps 142: .Qq description
143: is the manual's short description.
144: If an architecture is specified for the manual, it is displayed as
145: .Pp
146: .D1 title(cat/arch) \- description
147: .Pp
148: Resulting manuals may be accessed as
149: .Pp
1.3 kristaps 150: .Dl $ man \-s sec title
1.1 kristaps 151: .Pp
152: If an architecture is specified in the output, use
153: .Pp
1.3 kristaps 154: .Dl $ man \-s sec \-S arch title
1.6 kristaps 155: .Sh ENVIRONMENT
156: .Bl -tag -width Ds
157: .It Ev MANPATH
158: Comma-separated paths overriding the default list of paths searched for
159: manual databases.
160: Invalid paths, or paths without manual databases, are ignored.
1.7 ! kristaps 161: Takes precedence over
! 162: .Fl M .
1.6 kristaps 163: .El
1.1 kristaps 164: .\" .Sh FILES
165: .Sh EXIT STATUS
166: .Ex -std
167: .Sh EXAMPLES
168: Search for
1.4 kristaps 169: .Qq mdoc
170: within the manual name and description:
171: .Pp
172: .Dl $ apropos mdoc
173: .Pp
174: Two variants of searching for
175: .Qq mdoc ,
176: .Qq roff ,
177: or
178: .Qq man
179: within manual names and descriptions:
180: .Pp
181: .Dl $ apropos mdoc roff man
182: .Dl $ apropos mdoc \-o roff \-o man
183: .Pp
184: Search for
1.1 kristaps 185: .Qq optind
1.4 kristaps 186: and
187: .Qq optarg
188: as variable names in the library category:
1.1 kristaps 189: .Pp
1.4 kristaps 190: .Dl $ apropos \-s 3 \(dqVa~^optind$\(dq -a \(dqVa~^optarg$\(dq
1.1 kristaps 191: .Pp
1.4 kristaps 192: Search for all manuals referencing
1.1 kristaps 193: .Qq POSIX
194: in any letter case:
195: .Pp
1.4 kristaps 196: .Dl $ apropos \-\- \-i posix
1.1 kristaps 197: .Sh SEE ALSO
198: .Xr man 1 ,
199: .Xr mandoc 1 ,
200: .Xr re_format 7
201: .Sh AUTHORS
202: The
203: .Nm
204: utility was written by
1.2 kristaps 205: .An Kristaps Dzonsons ,
206: .Mt kristaps@bsd.lv .
CVSweb