external/bsd/mdocml/dist/apropos.1

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