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