makewhatis.8

   1 .\" $Id: makewhatis.8,v 1.7 2022/03/16 23:26:14 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: March 16 2022 $
  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 .
  56 .Pp
  57 By default,
  58 .Nm
  59 creates a database in each
  60 .Ar dir
  61 using the files
  62 .Sm off
  63 .Sy man Ar section Li /
  64 .Op Ar arch Li /
  65 .Ar title . section
  66 .Sm on
  67 and
  68 .Sm off
  69 .Sy cat Ar section Li /
  70 .Op Ar arch Li /
  71 .Ar title . Sy 0
  72 .Sm on
  73 in that directory.
  74 Existing databases are replaced.
  75 If a directory contains no manual pages, no database is created in that
  76 directory.
  77 If
  78 .Ar dir
  79 is not provided,
  80 .Nm
  81 uses the default paths stipulated by
  82 .Xr man.conf 5 .
  83 .Pp
  84 The arguments are as follows:
  85 .Bl -tag -width "-C file"
  86 .It Fl a
  87 Use all directories and files found below
  88 .Ar dir ... .
  89 .It Fl C Ar file
  90 Specify an alternative configuration
  91 .Ar file
  92 in
  93 .Xr man.conf 5
  94 format.
  95 .It Fl D
  96 Display all files added or removed to the index.
  97 With a second
  98 .Fl D ,
  99 also show all keywords added for each file.
 100 .It Fl d Ar dir
 101 Merge (remove and re-add)
 102 .Ar
 103 to the database in
 104 .Ar dir .
 105 .It Fl n
 106 Do not create or modify any database; scan and parse only,
 107 and print manual page names and descriptions to standard output.
 108 .It Fl p
 109 Print warnings about potential problems with manual pages
 110 to the standard error output.
 111 .It Fl Q
 112 Quickly build reduced-size databases
 113 by reading only the NAME sections of manuals.
 114 The resulting databases will usually contain names and descriptions only.
 115 .It Fl T Cm utf8
 116 Use UTF-8 encoding instead of ASCII for strings stored in the databases.
 117 .It Fl t Ar
 118 Check the given
 119 .Ar files
 120 for potential problems.
 121 Implies
 122 .Fl a ,
 123 .Fl n ,
 124 and
 125 .Fl p .
 126 All diagnostic messages are printed to the standard output;
 127 the standard error output is not used.
 128 .It Fl u Ar dir
 129 Remove
 130 .Ar
 131 from the database in
 132 .Ar dir .
 133 If that causes the database to become empty, also delete the database file.
 134 .El
 135 .Pp
 136 If fatal parse errors are encountered while parsing, the offending file
 137 is printed to stderr, omitted from the index, and the parse continues
 138 with the next input file.
 139 .Sh ENVIRONMENT
 140 .Bl -tag -width MANPATH
 141 .It Ev MANPATH
 142 A colon-separated list of directories to create databases in.
 143 Ignored if a
 144 .Ar dir
 145 argument or the
 146 .Fl t
 147 option is specified.
 148 .El
 149 .Sh FILES
 150 .Bl -tag -width Ds
 151 .It Pa mandoc.db
 152 A database of manpages relative to the directory of the file.
 153 This file is portable across architectures and systems, so long as the
 154 manpage hierarchy it indexes does not change.
 155 .It Pa /etc/man.conf
 156 The default
 157 .Xr man 1
 158 configuration file.
 159 .El
 160 .Sh EXIT STATUS
 161 The
 162 .Nm
 163 utility exits with one of the following values:
 164 .Pp
 165 .Bl -tag -width Ds -compact
 166 .It 0
 167 No errors occurred.
 168 .It 5
 169 Invalid command line arguments were specified.
 170 No input files have been read.
 171 .It 6
 172 An operating system error occurred, for example memory exhaustion or an
 173 error accessing input files.
 174 Such errors cause
 175 .Nm
 176 to exit at once, possibly in the middle of parsing or formatting a file.
 177 The output databases are corrupt and should be removed.
 178 .El
 179 .Sh SEE ALSO
 180 .Xr apropos 1 ,
 181 .Xr man 1 ,
 182 .Xr whatis 1 ,
 183 .Xr man.conf 5
 184 .Sh HISTORY
 185 A
 186 .Nm
 187 utility first appeared in
 188 .Bx 2 .
 189 It was rewritten in
 190 .Xr perl 1
 191 for
 192 .Ox 2.7
 193 and in C for
 194 .Ox 5.6 .
 195 .Pp
 196 The
 197 .Ar dir
 198 argument first appeared in
 199 .Nx 1.0 ;
 200 the options
 201 .Fl dpt
 202 in
 203 .Ox 2.7 ;
 204 the option
 205 .Fl u
 206 in
 207 .Ox 3.4 ;
 208 and the options
 209 .Fl aCDnQT
 210 in
 211 .Ox 5.6 .
 212 .Sh AUTHORS
 213 .An -nosplit
 214 .An Bill Joy
 215 wrote the original
 216 .Bx
 217 .Nm
 218 in February 1979,
 219 .An Marc Espie
 220 started the Perl version in 2000,
 221 and the current version of
 222 .Nm
 223 was written by
 224 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 225 and
 226 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .