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