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