contrib/mdocml/apropos.1

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