contrib/mdocml/whatis.1

   1 .\"     $Id: whatis.1,v 1.8 2012/03/24 01:54:43 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 WHATIS 1
  19 .Os
  20 .Sh NAME
  21 .Nm whatis
  22 .Nd search for manual pages by page names
  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 name ...
  31 .Sh DESCRIPTION
  32 The
  33 .Nm
  34 utility searches databases generated by
  35 .Xr mandocdb 8
  36 for manuals containing the word
  37 .Ar name
  38 in their page name, ignoring case.
  39 It returns the header lines from all matching pages.
  40 You can then use the
  41 .Xr man 1
  42 command to get more information.
  43 .Pp
  44 By default,
  45 .Nm
  46 searches for
  47 .Xr mandocdb 8
  48 databases in the default paths stipulated by
  49 .Xr man 1 .
  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 The options 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
  63 .Ar manpath
  64 instead of the default list of paths searched for
  65 .Xr mandocdb 8
  66 databases.
  67 Invalid paths, or paths without manual databases, are ignored.
  68 .It Fl m Ar manpath
  69 Prepend the colon-separated
  70 .Ar manpath
  71 to the list of paths searched 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 Results are sorted by manual title, with output formatted as
  85 .Pp
  86 .D1 title(sec) \- description
  87 .Pp
  88 Where
  89 .Qq title
  90 is the manual's title (note multiple manual names may exist for one
  91 title),
  92 .Qq sec
  93 is the manual section, and
  94 .Qq description
  95 is the manual's short description.
  96 If an architecture is specified for the manual, it is displayed as
  97 .Pp
  98 .D1 title(cat/arch) \- description
  99 .Pp
 100 If on a TTY, results are prefixed with a numeric identifier.
 101 .Pp
 102 .D1 [index] title(cat) \- description
 103 .Pp
 104 One may choose a manual be entering the index at the prompt.
 105 Valid choices are displayed using
 106 .Ev MANPAGER ,
 107 or failing that ,
 108 .Ev PAGER
 109 or just
 110 .Xr more 1 .
 111 Source pages are formatted with
 112 .Xr mandoc 1 ;
 113 preformatted pages with
 114 .Xr cat 1 .
 115 .Pp
 116 .Nm
 117 is identical to running
 118 .Xr apropos 1
 119 as follows:
 120 .Pp
 121 .Dl $ apropos -- -i 'Nm~[[:<:]]term[[:>:]]'
 122 .Sh ENVIRONMENT
 123 .Bl -tag -width Ds
 124 .It Ev MANPAGER
 125 Default pager for manuals.
 126 If this is unset, falls back to
 127 .Ev Pager .
 128 .It Ev PAGER
 129 The second choice for a manual pager.
 130 If this is unset, use
 131 .Xr more 1 .
 132 .It Ev MANPATH
 133 Colon-separated paths modifying the default list of paths searched for
 134 manual databases.
 135 Invalid paths, or paths without manual databases, are ignored.
 136 Overridden by
 137 .Fl M .
 138 If
 139 .Ev MANPATH
 140 begins with a
 141 .Sq \&: ,
 142 it is appended to the default list;
 143 else if it ends with
 144 .Sq \&: ,
 145 it is prepended to the default list; else if it contains
 146 .Sq \&:: ,
 147 the default list is inserted between the colons.
 148 If none of these conditions are met, it overrides the default list.
 149 .El
 150 .Sh FILES
 151 .Bl -tag -width "/etc/man.conf" -compact
 152 .It Pa whatis.db
 153 name of the
 154 .Xr mandocdb 8
 155 keyword database
 156 .It Pa whatis.index
 157 name of the
 158 .Xr mandocdb 8
 159 filename database
 160 .It Pa /etc/man.conf
 161 default
 162 .Xr man 1
 163 configuration file
 164 .El
 165 .Sh EXIT STATUS
 166 .Ex -std
 167 .Sh SEE ALSO
 168 .Xr apropos 1 ,
 169 .Xr man 1 ,
 170 .Xr man.conf 5 ,
 171 .Xr mandocdb 8
 172 .Sh HISTORY
 173 The
 174 .Nm
 175 utility first appeared in
 176 .Bx 2 .
 177 It was rewritten from scratch as part of the
 178 .Xr mandocdb 8
 179 project for
 180 .Ox 5.1 .
 181 .Sh AUTHORS
 182 .An -nosplit
 183 .An Bill Joy
 184 wrote the original
 185 .Bx
 186 .Nm
 187 in 1979.
 188 The current version was written by
 189 .An Kristaps Dzonsons ,
 190 .Mt kristaps@bsd.lv .