apropos.1

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