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