contrib/mdocml/whatis.1

   1 .\"     $Id: whatis.1,v 1.7.2.2 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 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 path
  27 .Op Fl m Ar path
  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 .Pp
  51 The options are as follows:
  52 .Bl -tag -width Ds
  53 .It Fl C Ar file
  54 Specify an alternative configuration
  55 .Ar file
  56 in
  57 .Xr man.conf 5
  58 format.
  59 .It Fl M Ar path
  60 Use the colon-separated
  61 .Ar path
  62 instead of the default list of paths searched for
  63 .Xr mandocdb 8
  64 databases.
  65 Invalid paths, or paths without manual databases, are ignored.
  66 .It Fl m Ar path
  67 Prepend the colon-separated
  68 .Ar path
  69 to the list of paths searched 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 Results are sorted by manual title, with output formatted as
  83 .Pp
  84 .D1 title(sec) \- description
  85 .Pp
  86 Where
  87 .Qq title
  88 is the manual's title (note multiple manual names may exist for one
  89 title),
  90 .Qq sec
  91 is the manual section, and
  92 .Qq description
  93 is the manual's short description.
  94 If an architecture is specified for the manual, it is displayed as
  95 .Pp
  96 .D1 title(cat/arch) \- description
  97 .Pp
  98 Resulting manuals may be accessed as
  99 .Pp
 100 .Dl $ man \-s sec title
 101 .Pp
 102 If an architecture is specified in the output, use
 103 .Pp
 104 .Dl $ man \-s sec \-S arch title
 105 .Pp
 106 .Nm
 107 is identical to running
 108 .Xr apropos 1
 109 as follows:
 110 .Pp
 111 .Dl $ apropos -- -i 'Nm~[[:<:]]term[[:>:]]'
 112 .Sh ENVIRONMENT
 113 .Bl -tag -width Ds
 114 .It Ev MANPATH
 115 Colon-separated paths modifying the default list of paths searched for
 116 manual databases.
 117 Invalid paths, or paths without manual databases, are ignored.
 118 Overridden by
 119 .Fl M .
 120 If
 121 .Ev MANPATH
 122 begins with a
 123 .Sq \&: ,
 124 it is appended to the default list;
 125 else if it ends with
 126 .Sq \&: ,
 127 it is prepended to the default list; else if it contains
 128 .Sq \&:: ,
 129 the default list is inserted between the colons.
 130 If none of these conditions are met, it overrides the default list.
 131 .El
 132 .Sh FILES
 133 .Bl -tag -width "/etc/man.conf" -compact
 134 .It Pa mandoc.db
 135 name of the
 136 .Xr mandocdb 8
 137 keyword database
 138 .It Pa mandoc.index
 139 name of the
 140 .Xr mandocdb 8
 141 filename database
 142 .It Pa /etc/man.conf
 143 default
 144 .Xr man 1
 145 configuration file
 146 .El
 147 .Sh EXIT STATUS
 148 .Ex -std
 149 .Sh SEE ALSO
 150 .Xr apropos 1 ,
 151 .Xr man 1 ,
 152 .Xr man.conf 5 ,
 153 .Xr mandocdb 8
 154 .Sh HISTORY
 155 The
 156 .Nm
 157 utility first appeared in
 158 .Bx 2 .
 159 It was rewritten from scratch as part of the
 160 .Xr mandocdb 8
 161 project for
 162 .Ox 5.1 .
 163 .Sh AUTHORS
 164 .An -nosplit
 165 .An Bill Joy
 166 wrote the original
 167 .Bx
 168 .Nm
 169 in 1979.
 170 The current version was written by
 171 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .