apropos.1

   1 .\"     $Id: apropos.1,v 1.15 2011/12/25 16:53:51 schwarze 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: December 25 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 C Ar file
  26 .Op Fl M Ar manpath
  27 .Op Fl m Ar manpath
  28 .Op Fl S Ar arch
  29 .Op Fl s Ar section
  30 .Ar expression ...
  31 .Sh DESCRIPTION
  32 The
  33 .Nm
  34 utility queries manual page databases generated by
  35 .Xr mandocdb 8 ,
  36 evaluating on
  37 .Ar expression
  38 for each file in each database.
  39 Its arguments are as follows:
  40 .Bl -tag -width Ds
  41 .It Fl C Ar file
  42 Specify an alternative configuration
  43 .Ar file
  44 in
  45 .Xr man.conf 5
  46 format.
  47 .It Fl M Ar manpath
  48 Use the colon-separated path instead of the default list of paths
  49 searched for
  50 .Xr mandocdb 8
  51 databases.
  52 Invalid paths, or paths without manual databases, are ignored.
  53 .It Fl m Ar manpath
  54 Prepend the colon-separated paths to the list of paths searched
  55 for
  56 .Xr mandocdb 8
  57 databases.
  58 Invalid paths, or paths without manual databases, are ignored.
  59 .It Fl S Ar arch
  60 Search only for a particular architecture.
  61 .It Fl s Ar cat
  62 Search only for a manual section.
  63 See
  64 .Xr man 1
  65 for a listing of manual sections.
  66 .El
  67 .Pp
  68 An
  69 .Ar expression
  70 consists of search terms joined by logical operators
  71 .Fl a
  72 .Pq and
  73 and
  74 .Fl o
  75 .Pq or .
  76 The
  77 .Fl a
  78 operator has precedence over
  79 .Fl o
  80 and both are evaluated left-to-right.
  81 .Bl -tag -width Ds
  82 .It \&( Ar expr No \&)
  83 True if the subexpression
  84 .Ar expr
  85 is true.
  86 .It Ar expr1 Fl a Ar expr2
  87 True if both
  88 .Ar expr1
  89 and
  90 .Ar expr2
  91 are true (logical
  92 .Qq and ) .
  93 .It Ar expr1 Oo Fl o Oc Ar expr2
  94 True if
  95 .Ar expr1
  96 and/or
  97 .Ar expr2
  98 evaluate to true (logical
  99 .Qq or ) .
 100 .It Ar term
 101 True if
 102 .Ar term
 103 is satisfied.
 104 This has syntax
 105 .Li [key[,key]*(=~)]?val ,
 106 where operand
 107 .Cm key
 108 is an
 109 .Xr mdoc 7
 110 macro to query and
 111 .Cm val
 112 is its value.
 113 See
 114 .Sx Macro Keys
 115 for a list of available keys.
 116 Operator
 117 .Li \&=
 118 evaluates a substring, while
 119 .Li \&~
 120 evaluates a regular expression.
 121 .It Fl i Ar term
 122 If
 123 .Ar term
 124 is a regular expression, it
 125 is evaluated case-insensitively.
 126 Has no effect on substring terms.
 127 .El
 128 .Pp
 129 By default,
 130 .Nm
 131 searches for
 132 .Xr mandocdb 8
 133 databases in the default paths stipulated by
 134 .Xr man 1 ,
 135 parses terms as case-sensitive regular expressions
 136 .Pq the Li \&~ operator
 137 over manual names and descriptions
 138 .Pq the Li \&Nm No and Li \&Nd No macro keys .
 139 Multiple terms imply pairwise
 140 .Fl o .
 141 Results are sorted by manual title, with output formatted as
 142 .Pp
 143 .D1 title(sec) \- description
 144 .Pp
 145 Where
 146 .Qq title
 147 is the manual's title (note multiple manual names may exist for one
 148 title),
 149 .Qq sec
 150 is the manual section, and
 151 .Qq description
 152 is the manual's short description.
 153 If an architecture is specified for the manual, it is displayed as
 154 .Pp
 155 .D1 title(cat/arch) \- description
 156 .Pp
 157 Resulting manuals may be accessed as
 158 .Pp
 159 .Dl $ man \-s sec title
 160 .Pp
 161 If an architecture is specified in the output, use
 162 .Pp
 163 .Dl $ man \-s sec \-S arch title
 164 .Ss Macro Keys
 165 Queries evaluate over a subset of
 166 .Xr mdoc 7
 167 macros indexed by
 168 .Xr mandocdb 8 .
 169 In addition to the macro keys listed below, the special key
 170 .Cm any
 171 may be used to match any available macro key.
 172 .Pp
 173 Names and description:
 174 .Bl -column "xLix" description -offset indent -compact
 175 .It Li \&Nm Ta manual name
 176 .It Li \&Nd Ta one-line manual description
 177 .El
 178 .Pp
 179 Sections and cross references:
 180 .Bl -column "xLix" description -offset indent -compact
 181 .It Li \&Sh Ta section header (excluding standard sections)
 182 .It Li \&Ss Ta subsection header
 183 .It Li \&Xr Ta cross reference to another manual page
 184 .It Li \&Rs Ta bibliographic reference
 185 .El
 186 .Pp
 187 Semantic markup for command line utilities:
 188 .Bl -column "xLix" description -offset indent -compact
 189 .It Li \&Fl Ta command line options (flags)
 190 .It Li \&Cm Ta command modifier
 191 .It Li \&Ar Ta command argument
 192 .It Li \&Ic Ta internal or interactive command
 193 .It Li \&Ev Ta environmental variable
 194 .It Li \&Pa Ta file system path
 195 .El
 196 .Pp
 197 Semantic markup for function libraries:
 198 .Bl -column "xLix" description -offset indent -compact
 199 .It Li \&Lb Ta function library name
 200 .It Li \&In Ta include file
 201 .It Li \&Ft Ta function return type
 202 .It Li \&Fn Ta function name
 203 .It Li \&Fa Ta function argument type and name
 204 .It Li \&Vt Ta variable type
 205 .It Li \&Va Ta variable name
 206 .It Li \&Dv Ta defined variable or preprocessor constant
 207 .It Li \&Er Ta error constant
 208 .It Li \&Ev Ta environmental variable
 209 .El
 210 .Pp
 211 Various semantic markup:
 212 .Bl -column "xLix" description -offset indent -compact
 213 .It Li \&An Ta author name
 214 .It Li \&Lk Ta hyperlink
 215 .It Li \&Mt Ta Do mailto Dc hyperlink
 216 .It Li \&Cd Ta kernel configuration declaration
 217 .It Li \&Ms Ta mathematical symbol
 218 .It Li \&Tn Ta tradename
 219 .El
 220 .Pp
 221 Physical markup:
 222 .Bl -column "xLix" description -offset indent -compact
 223 .It Li \&Em Ta italic font or underline
 224 .It Li \&Sy Ta boldface font
 225 .It Li \&Li Ta typewriter font
 226 .El
 227 .Pp
 228 Text production:
 229 .Bl -column "xLix" description -offset indent -compact
 230 .It Li \&St Ta reference to a standards document
 231 .It Li \&At Ta At No version reference
 232 .It Li \&Bx Ta Bx No version reference
 233 .It Li \&Bsx Ta Bsx No version reference
 234 .It Li \&Nx Ta Nx No version reference
 235 .It Li \&Fx Ta Fx No version reference
 236 .It Li \&Ox Ta Ox No version reference
 237 .It Li \&Dx Ta Dx No version reference
 238 .El
 239 .Sh ENVIRONMENT
 240 .Bl -tag -width Ds
 241 .It Ev MANPATH
 242 Colon-separated paths modifying the default list of paths searched for
 243 manual databases.
 244 Invalid paths, or paths without manual databases, are ignored.
 245 Overridden by
 246 .Fl M .
 247 If
 248 .Ev MANPATH
 249 begins with a
 250 .Sq \&: ,
 251 it is appended to the default list;
 252 else if it ends with
 253 .Sq \&: ,
 254 it is prepended to the default list; else if it contains
 255 .Sq \&:: ,
 256 the default list is inserted between the colons.
 257 If none of these conditions are met, it overrides the default list.
 258 .El
 259 .Sh FILES
 260 .Bl -tag -width "/etc/man.conf" -compact
 261 .It Pa whatis.db
 262 name of the
 263 .Xr mandocdb 8
 264 keyword database
 265 .It Pa whatis.index
 266 name of the
 267 .Xr mandocdb 8
 268 filename database
 269 .It Pa /etc/man.conf
 270 default
 271 .Xr man 1
 272 configuration file
 273 .El
 274 .Sh EXIT STATUS
 275 .Ex -std
 276 .Sh EXAMPLES
 277 Search for
 278 .Qq mdoc
 279 as a substring and regular expression
 280 within each manual name and description:
 281 .Pp
 282 .Dl $ apropos mdoc
 283 .Dl $ apropos ~^mdoc$
 284 .Pp
 285 Include matches for
 286 .Qq roff
 287 and
 288 .Qq man
 289 for the regular expression case:
 290 .Pp
 291 .Dl $ apropos ~^mdoc$ roff man
 292 .Dl $ apropos ~^mdoc$ \-o roff \-o man
 293 .Pp
 294 Search for
 295 .Qq optind
 296 and
 297 .Qq optarg
 298 as variable names in the library category:
 299 .Pp
 300 .Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$
 301 .Sh SEE ALSO
 302 .Xr man 1 ,
 303 .Xr re_format 7 ,
 304 .Xr mandocdb 8
 305 .Sh AUTHORS
 306 The
 307 .Nm
 308 utility was written by
 309 .An Kristaps Dzonsons ,
 310 .Mt kristaps@bsd.lv .