apropos.1

   1 .\"     $Id: apropos.1,v 1.12 2011/11/29 10:59:19 kristaps Exp $
   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 .\"
  17 .Dd $Mdocdate: November 29 2011 $
  18 .Dt APROPOS 1
  19 .Os
  20 .Sh NAME
  21 .Nm apropos
  22 .Nd search manual page databases
  23 .Sh SYNOPSIS
  24 .Nm
  25 .Op Fl M Ar manpath
  26 .Op Fl m Ar manpath
  27 .Op Fl S Ar arch
  28 .Op Fl s Ar section
  29 .Ar expression...
  30 .Sh DESCRIPTION
  31 The
  32 .Nm
  33 utility queries manual page databases generated by
  34 .Xr mandocdb 8 ,
  35 evaluating on
  36 .Ar expression
  37 for each file in each database.
  38 Its arguments are as follows:
  39 .Bl -tag -width Ds
  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.
  46 .It Fl m Ar manpath
  47 Prepend the colon-separated paths to the list of paths searched
  48 for
  49 .Xr mandocdb 8
  50 databases.
  51 Invalid paths, or paths without manual databases, are ignored.
  52 .It Fl S Ar arch
  53 Search only for a particular architecture.
  54 .It Fl s Ar cat
  55 Search only for a manual section.
  56 See
  57 .Xr man 1
  58 for a listing of manual sections.
  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
 100 .Cm key
 101 is an
 102 .Xr mdoc 7
 103 macro to query and
 104 .Cm val
 105 is its value.
 106 See
 107 .Sx Macro Keys
 108 for a list of available keys.
 109 Operator
 110 .Li \&=
 111 evaluates a substring, while
 112 .Li \&~
 113 evaluates a regular expression.
 114 .It Fl i Ar term
 115 If
 116 .Ar term
 117 is a regular expression, it
 118 is evaluated case-insensitively.
 119 Has no effect on substring terms.
 120 .El
 121 .Pp
 122 By default,
 123 .Nm
 124 searches for
 125 .Xr mandocdb 8
 126 databases in the default paths stipulated by
 127 .Xr man 1 ,
 128 parses terms as case-sensitive regular expressions
 129 .Pq the Li \&~ operator
 130 over manual names and descriptions
 131 .Pq the Li \&Nm No and Li \&Nd No macro keys .
 132 Multiple terms imply pairwise
 133 .Fl o .
 134 Results are sorted by manual title, with output formatted as
 135 .Pp
 136 .D1 title(sec) \- description
 137 .Pp
 138 Where
 139 .Qq title
 140 is the manual's title (note multiple manual names may exist for one
 141 title),
 142 .Qq sec
 143 is the manual section, and
 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
 152 .Dl $ man \-s sec title
 153 .Pp
 154 If an architecture is specified in the output, use
 155 .Pp
 156 .Dl $ man \-s sec \-S arch title
 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
 232 .Sh ENVIRONMENT
 233 .Bl -tag -width Ds
 234 .It Ev MANPATH
 235 Colon-separated paths overriding the default list of paths searched for
 236 manual databases.
 237 Invalid paths, or paths without manual databases, are ignored.
 238 Overridden by
 239 .Fl M .
 240 .El
 241 .Sh EXIT STATUS
 242 .Ex -std
 243 .Sh EXAMPLES
 244 Search for
 245 .Qq mdoc
 246 as a substring and regular expression
 247 within each manual name and description:
 248 .Pp
 249 .Dl $ apropos mdoc
 250 .Dl $ apropos ~^mdoc$
 251 .Pp
 252 Include matches for
 253 .Qq roff
 254 and
 255 .Qq man
 256 for the regular expression case:
 257 .Pp
 258 .Dl $ apropos ~^mdoc$ roff man
 259 .Dl $ apropos ~^mdoc$ \-o roff \-o man
 260 .Pp
 261 Search for
 262 .Qq optind
 263 and
 264 .Qq optarg
 265 as variable names in the library category:
 266 .Pp
 267 .Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$
 268 .Sh SEE ALSO
 269 .Xr man 1 ,
 270 .Xr re_format 7 ,
 271 .Xr mandocdb 8
 272 .Sh AUTHORS
 273 The
 274 .Nm
 275 utility was written by
 276 .An Kristaps Dzonsons ,
 277 .Mt kristaps@bsd.lv .