apropos.1

   1 .\"     $Id: apropos.1,v 1.9 2011/11/26 22:38:11 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: November 26 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 .Li key
 101 is an
 102 .Xr mdoc 7
 103 macro to query and
 104 .Li val
 105 is its value.
 106 Operator
 107 .Li \&=
 108 evaluates a substring, while
 109 .Li \&~
 110 evaluates a regular expression.
 111 .It Fl i Ar term
 112 Same as
 113 .Ar term ,
 114 but
 115 .Ar term
 116 is evaluated case-insensitively.
 117 .El
 118 .Pp
 119 By default,
 120 .Nm
 121 searches for
 122 .Xr mandocdb 8
 123 databases in the default paths stipulated by
 124 .Xr man 1 ,
 125 parses terms as case-sensitive regular expressions
 126 .Pq the Li \&~ operator
 127 over manual names and descriptions
 128 .Pq the Li \&Nm No and Li \&Nd No macros .
 129 Multiple terms imply pairwise
 130 .Fl o .
 131 Results are sorted by manual title, with output formatted as
 132 .Pp
 133 .D1 title(sec) \- description
 134 .Pp
 135 Where
 136 .Qq title
 137 is the manual's title (note multiple manual names may exist for one
 138 title),
 139 .Qq sec
 140 is the manual section, and
 141 .Qq description
 142 is the manual's short description.
 143 If an architecture is specified for the manual, it is displayed as
 144 .Pp
 145 .D1 title(cat/arch) \- description
 146 .Pp
 147 Resulting manuals may be accessed as
 148 .Pp
 149 .Dl $ man \-s sec title
 150 .Pp
 151 If an architecture is specified in the output, use
 152 .Pp
 153 .Dl $ man \-s sec \-S arch title
 154 .Sh ENVIRONMENT
 155 .Bl -tag -width Ds
 156 .It Ev MANPATH
 157 Colon-separated paths overriding the default list of paths searched for
 158 manual databases.
 159 Invalid paths, or paths without manual databases, are ignored.
 160 Overridden by
 161 .Fl M .
 162 .El
 163 .\" .Sh FILES
 164 .Sh EXIT STATUS
 165 .Ex -std
 166 .Sh EXAMPLES
 167 Search for
 168 .Qq mdoc
 169 within the manual name and description:
 170 .Pp
 171 .Dl $ apropos mdoc
 172 .Pp
 173 Two variants of searching for
 174 .Qq mdoc ,
 175 .Qq roff ,
 176 or
 177 .Qq man
 178 within manual names and descriptions:
 179 .Pp
 180 .Dl $ apropos mdoc roff man
 181 .Dl $ apropos mdoc \-o roff \-o man
 182 .Pp
 183 Search for
 184 .Qq optind
 185 and
 186 .Qq optarg
 187 as variable names in the library category:
 188 .Pp
 189 .Dl $ apropos \-s 3 \(dqVa~^optind$\(dq -a \(dqVa~^optarg$\(dq
 190 .Pp
 191 Search for all manuals referencing
 192 .Qq POSIX
 193 in any letter case:
 194 .Pp
 195 .Dl $ apropos \-\- \-i posix
 196 .Sh SEE ALSO
 197 .Xr man 1 ,
 198 .Xr mandoc 1 ,
 199 .Xr re_format 7
 200 .Sh AUTHORS
 201 The
 202 .Nm
 203 utility was written by
 204 .An Kristaps Dzonsons ,
 205 .Mt kristaps@bsd.lv .