Annotation of mandoc/makewhatis.8, Revision 1.6
1.6 ! schwarze 1: .\" $Id: makewhatis.8,v 1.5 2017/03/18 19:51:19 schwarze Exp $
1.1 schwarze 2: .\"
3: .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
1.5 schwarze 4: .\" Copyright (c) 2011, 2012, 2014, 2017 Ingo Schwarze <schwarze@openbsd.org>
1.1 schwarze 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: .\"
1.6 ! schwarze 18: .Dd $Mdocdate: March 18 2017 $
1.1 schwarze 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
1.2 schwarze 44: .Op Fl DQ
1.1 schwarze 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.
1.6 ! schwarze 77: If a directory contains no manual pages, no database is created in that
! 78: directory.
1.1 schwarze 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 ,
1.3 schwarze 101: also show all keywords added for each file.
1.1 schwarze 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 .
1.6 ! schwarze 135: If that causes the database to become empty, also delete the database file.
1.1 schwarze 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.
1.5 schwarze 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
1.1 schwarze 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 .
CVSweb