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