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