contrib/mdocml/apropos.1

   1 .\"     $Id: apropos.1,v 1.16.2.3 2013/10/05 01:25:20 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: October 5 2013 $
  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 path
  27 .Op Fl m Ar path
  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 .Pq the Li \&~ operator
  48 over manual names and descriptions
  49 .Pq the Li \&Nm No and Li \&Nd No macro keys .
  50 Multiple terms imply pairwise
  51 .Fl o .
  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 path
  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 path
  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 Resulting manuals may be accessed as
 160 .Pp
 161 .Dl $ man \-s sec title
 162 .Pp
 163 If an architecture is specified in the output, use
 164 .Pp
 165 .Dl $ man \-s sec \-S arch title
 166 .Ss Macro Keys
 167 Queries evaluate over a subset of
 168 .Xr mdoc 7
 169 macros indexed by
 170 .Xr mandocdb 8 .
 171 In addition to the macro keys listed below, the special key
 172 .Cm any
 173 may be used to match any available macro key.
 174 .Pp
 175 Names and description:
 176 .Bl -column "xLix" description -offset indent -compact
 177 .It Li \&Nm Ta manual name
 178 .It Li \&Nd Ta one-line manual description
 179 .El
 180 .Pp
 181 Sections and cross references:
 182 .Bl -column "xLix" description -offset indent -compact
 183 .It Li \&Sh Ta section header (excluding standard sections)
 184 .It Li \&Ss Ta subsection header
 185 .It Li \&Xr Ta cross reference to another manual page
 186 .It Li \&Rs Ta bibliographic reference
 187 .El
 188 .Pp
 189 Semantic markup for command line utilities:
 190 .Bl -column "xLix" description -offset indent -compact
 191 .It Li \&Fl Ta command line options (flags)
 192 .It Li \&Cm Ta command modifier
 193 .It Li \&Ar Ta command argument
 194 .It Li \&Ic Ta internal or interactive command
 195 .It Li \&Ev Ta environmental variable
 196 .It Li \&Pa Ta file system path
 197 .El
 198 .Pp
 199 Semantic markup for function libraries:
 200 .Bl -column "xLix" description -offset indent -compact
 201 .It Li \&Lb Ta function library name
 202 .It Li \&In Ta include file
 203 .It Li \&Ft Ta function return type
 204 .It Li \&Fn Ta function name
 205 .It Li \&Fa Ta function argument type and name
 206 .It Li \&Vt Ta variable type
 207 .It Li \&Va Ta variable name
 208 .It Li \&Dv Ta defined variable or preprocessor constant
 209 .It Li \&Er Ta error constant
 210 .It Li \&Ev Ta environmental variable
 211 .El
 212 .Pp
 213 Various semantic markup:
 214 .Bl -column "xLix" description -offset indent -compact
 215 .It Li \&An Ta author name
 216 .It Li \&Lk Ta hyperlink
 217 .It Li \&Mt Ta Do mailto Dc hyperlink
 218 .It Li \&Cd Ta kernel configuration declaration
 219 .It Li \&Ms Ta mathematical symbol
 220 .It Li \&Tn Ta tradename
 221 .El
 222 .Pp
 223 Physical markup:
 224 .Bl -column "xLix" description -offset indent -compact
 225 .It Li \&Em Ta italic font or underline
 226 .It Li \&Sy Ta boldface font
 227 .It Li \&Li Ta typewriter font
 228 .El
 229 .Pp
 230 Text production:
 231 .Bl -column "xLix" description -offset indent -compact
 232 .It Li \&St Ta reference to a standards document
 233 .It Li \&At Ta At No version reference
 234 .It Li \&Bx Ta Bx No version reference
 235 .It Li \&Bsx Ta Bsx No version reference
 236 .It Li \&Nx Ta Nx No version reference
 237 .It Li \&Fx Ta Fx No version reference
 238 .It Li \&Ox Ta Ox No version reference
 239 .It Li \&Dx Ta Dx No version reference
 240 .El
 241 .Sh ENVIRONMENT
 242 .Bl -tag -width Ds
 243 .It Ev MANPATH
 244 Colon-separated paths modifying the default list of paths searched for
 245 manual databases.
 246 Invalid paths, or paths without manual databases, are ignored.
 247 Overridden by
 248 .Fl M .
 249 If
 250 .Ev MANPATH
 251 begins with a
 252 .Sq \&: ,
 253 it is appended to the default list;
 254 else if it ends with
 255 .Sq \&: ,
 256 it is prepended to the default list; else if it contains
 257 .Sq \&:: ,
 258 the default list is inserted between the colons.
 259 If none of these conditions are met, it overrides the default list.
 260 .El
 261 .Sh FILES
 262 .Bl -tag -width "/etc/man.conf" -compact
 263 .It Pa mandoc.db
 264 name of the
 265 .Xr mandocdb 8
 266 keyword database
 267 .It Pa mandoc.index
 268 name of the
 269 .Xr mandocdb 8
 270 filename database
 271 .It Pa /etc/man.conf
 272 default
 273 .Xr man 1
 274 configuration file
 275 .El
 276 .Sh EXIT STATUS
 277 .Ex -std
 278 .Sh EXAMPLES
 279 Search for
 280 .Qq mdoc
 281 as a substring and regular expression
 282 within each manual name and description:
 283 .Pp
 284 .Dl $ apropos mdoc
 285 .Dl $ apropos ~^mdoc$
 286 .Pp
 287 Include matches for
 288 .Qq roff
 289 and
 290 .Qq man
 291 for the regular expression case:
 292 .Pp
 293 .Dl $ apropos ~^mdoc$ roff man
 294 .Dl $ apropos ~^mdoc$ \-o roff \-o man
 295 .Pp
 296 Search for
 297 .Qq optind
 298 and
 299 .Qq optarg
 300 as variable names in the library category:
 301 .Pp
 302 .Dl $ apropos \-s 3 Va~^optind \-a Va~^optarg$
 303 .Sh SEE ALSO
 304 .Xr man 1 ,
 305 .Xr re_format 7 ,
 306 .Xr mandocdb 8
 307 .Sh AUTHORS
 308 The
 309 .Nm
 310 utility was written by
 311 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .