bin/mandoc/makewhatis.8

   1 .\"     $Id: makewhatis.8,v 1.6 2017/05/17 22:27:12 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\" Copyright (c) 2011, 2012, 2014, 2017 Ingo Schwarze <schwarze@openbsd.org>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd $Mdocdate: May 17 2017 $
  19 .Dt MAKEWHATIS 8
  20 .Os
  21 .Sh NAME
  22 .Nm makewhatis
  23 .Nd index UNIX manuals
  24 .Sh SYNOPSIS
  25 .Nm
  26 .Op Fl aDnpQ
  27 .Op Fl T Cm utf8
  28 .Op Fl C Ar file
  29 .Nm
  30 .Op Fl aDnpQ
  31 .Op Fl T Cm utf8
  32 .Ar dir ...
  33 .Nm
  34 .Op Fl DnpQ
  35 .Op Fl T Cm utf8
  36 .Fl d Ar dir
  37 .Op Ar
  38 .Nm
  39 .Op Fl Dnp
  40 .Op Fl T Cm utf8
  41 .Fl u Ar dir
  42 .Op Ar
  43 .Nm
  44 .Op Fl DQ
  45 .Fl t Ar
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 utility extracts keywords from
  50 .Ux
  51 manuals and indexes them in a database for fast retrieval by
  52 .Xr apropos 1 ,
  53 .Xr whatis 1 ,
  54 and
  55 .Xr man 1 Ns 's
  56 .Fl k
  57 option.
  58 .Pp
  59 By default,
  60 .Nm
  61 creates a database in each
  62 .Ar dir
  63 using the files
  64 .Sm off
  65 .Sy man Ar section Li /
  66 .Op Ar arch Li /
  67 .Ar title . section
  68 .Sm on
  69 and
  70 .Sm off
  71 .Sy cat Ar section Li /
  72 .Op Ar arch Li /
  73 .Ar title . Sy 0
  74 .Sm on
  75 in that directory.
  76 Existing databases are replaced.
  77 If a directory contains no manual pages, no database is created in that
  78 directory.
  79 If
  80 .Ar dir
  81 is not provided,
  82 .Nm
  83 uses the default paths stipulated by
  84 .Xr man.conf 5 .
  85 .Pp
  86 The arguments are as follows:
  87 .Bl -tag -width "-C file"
  88 .It Fl a
  89 Use all directories and files found below
  90 .Ar dir ... .
  91 .It Fl C Ar file
  92 Specify an alternative configuration
  93 .Ar file
  94 in
  95 .Xr man.conf 5
  96 format.
  97 .It Fl D
  98 Display all files added or removed to the index.
  99 With a second
 100 .Fl D ,
 101 also show all keywords added for each file.
 102 .It Fl d Ar dir
 103 Merge (remove and re-add)
 104 .Ar
 105 to the database in
 106 .Ar dir .
 107 .It Fl n
 108 Do not create or modify any database; scan and parse only,
 109 and print manual page names and descriptions to standard output.
 110 .It Fl p
 111 Print warnings about potential problems with manual pages
 112 to the standard error output.
 113 .It Fl Q
 114 Quickly build reduced-size databases
 115 by reading only the NAME sections of manuals.
 116 The resulting databases will usually contain names and descriptions only.
 117 .It Fl T Cm utf8
 118 Use UTF-8 encoding instead of ASCII for strings stored in the databases.
 119 .It Fl t Ar
 120 Check the given
 121 .Ar files
 122 for potential problems.
 123 Implies
 124 .Fl a ,
 125 .Fl n ,
 126 and
 127 .Fl p .
 128 All diagnostic messages are printed to the standard output;
 129 the standard error output is not used.
 130 .It Fl u Ar dir
 131 Remove
 132 .Ar
 133 from the database in
 134 .Ar dir .
 135 If that causes the database to become empty, also delete the database file.
 136 .El
 137 .Pp
 138 If fatal parse errors are encountered while parsing, the offending file
 139 is printed to stderr, omitted from the index, and the parse continues
 140 with the next input file.
 141 .Sh ENVIRONMENT
 142 .Bl -tag -width MANPATH
 143 .It Ev MANPATH
 144 A colon-separated list of directories to create databases in.
 145 Ignored if a
 146 .Ar dir
 147 argument or the
 148 .Fl t
 149 option is specified.
 150 .El
 151 .Sh FILES
 152 .Bl -tag -width Ds
 153 .It Pa mandoc.db
 154 A database of manpages relative to the directory of the file.
 155 This file is portable across architectures and systems, so long as the
 156 manpage hierarchy it indexes does not change.
 157 .It Pa /etc/man.conf
 158 The default
 159 .Xr man 1
 160 configuration file.
 161 .El
 162 .Sh EXIT STATUS
 163 The
 164 .Nm
 165 utility exits with one of the following values:
 166 .Pp
 167 .Bl -tag -width Ds -compact
 168 .It 0
 169 No errors occurred.
 170 .It 5
 171 Invalid command line arguments were specified.
 172 No input files have been read.
 173 .It 6
 174 An operating system error occurred, for example memory exhaustion or an
 175 error accessing input files.
 176 Such errors cause
 177 .Nm
 178 to exit at once, possibly in the middle of parsing or formatting a file.
 179 The output databases are corrupt and should be removed.
 180 .El
 181 .Sh SEE ALSO
 182 .Xr apropos 1 ,
 183 .Xr man 1 ,
 184 .Xr whatis 1 ,
 185 .Xr man.conf 5
 186 .Sh HISTORY
 187 A
 188 .Nm
 189 utility first appeared in
 190 .Bx 2 .
 191 It was rewritten in
 192 .Xr perl 1
 193 for
 194 .Ox 2.7
 195 and in C for
 196 .Ox 5.6 .
 197 .Pp
 198 The
 199 .Ar dir
 200 argument first appeared in
 201 .Nx 1.0 ;
 202 the options
 203 .Fl dpt
 204 in
 205 .Ox 2.7 ;
 206 the option
 207 .Fl u
 208 in
 209 .Ox 3.4 ;
 210 and the options
 211 .Fl aCDnQT
 212 in
 213 .Ox 5.6 .
 214 .Sh AUTHORS
 215 .An -nosplit
 216 .An Bill Joy
 217 wrote the original
 218 .Bx
 219 .Nm
 220 in February 1979,
 221 .An Marc Espie
 222 started the Perl version in 2000,
 223 and the current version of
 224 .Nm
 225 was written by
 226 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 227 and
 228 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .