Annotation of src/usr.bin/mandoc/makewhatis.8, Revision 1.6
1.6 ! schwarze 1: .\" $Id: makewhatis.8,v 1.5 2014/03/17 08:31:54 schwarze Exp $
1.1 schwarze 2: .\"
1.5 schwarze 3: .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
4: .\" Copyright (c) 2011, 2012 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 17 2014 $
1.2 schwarze 19: .Dt MAKEWHATIS 8
1.1 schwarze 20: .Os
21: .Sh NAME
1.2 schwarze 22: .Nm makewhatis
1.1 schwarze 23: .Nd index UNIX manuals
24: .Sh SYNOPSIS
25: .Nm
1.6 ! schwarze 26: .Op Fl anQvW
! 27: .Op Fl T Cm utf8
1.1 schwarze 28: .Op Fl C Ar file
29: .Nm
1.6 ! schwarze 30: .Op Fl anQvW
! 31: .Op Fl T Cm utf8
1.1 schwarze 32: .Ar dir ...
33: .Nm
1.6 ! schwarze 34: .Op Fl nQvW
! 35: .Op Fl T Cm utf8
1.1 schwarze 36: .Fl d Ar dir
37: .Op Ar
38: .Nm
1.5 schwarze 39: .Op Fl nvW
1.6 ! schwarze 40: .Op Fl T Cm utf8
1.1 schwarze 41: .Fl u Ar dir
42: .Op Ar
43: .Nm
1.6 ! schwarze 44: .Op Fl Q
1.1 schwarze 45: .Fl t Ar
46: .Sh DESCRIPTION
47: The
48: .Nm
49: utility extracts keywords from
50: .Ux
1.5 schwarze 51: manuals and indexes them in a database for fast retrieval by
1.1 schwarze 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
1.5 schwarze 61: creates a database in each
1.1 schwarze 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
1.5 schwarze 75: in that directory.
76: Existing databases are replaced.
1.1 schwarze 77: If
78: .Ar dir
79: is not provided,
80: .Nm
81: uses the default paths stipulated by
1.5 schwarze 82: .Xr man.conf 5 .
1.1 schwarze 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 Ar dir
96: Merge (remove and re-add)
97: .Ar
98: to the database in
1.5 schwarze 99: .Ar dir .
100: .It Fl n
101: Do not create or modify any database;
102: scan and parse only.
1.6 ! schwarze 103: .It Fl Q
! 104: Quickly build reduced-size databases
! 105: by reading only the NAME sections of manuals.
! 106: The resulting databases will usually contain names and descriptions only.
! 107: .It Fl T Cm utf8
! 108: Use UTF-8 encoding instead of ASCII for strings stored in the databases.
1.1 schwarze 109: .It Fl t Ar
110: Check the given
111: .Ar files
112: for potential problems.
113: Implies
1.5 schwarze 114: .Fl a ,
115: .Fl n ,
1.1 schwarze 116: and
117: .Fl W .
118: All diagnostic messages are printed to the standard output;
119: the standard error output is not used.
120: .It Fl u Ar dir
121: Remove
122: .Ar
123: from the database in
1.5 schwarze 124: .Ar dir .
1.1 schwarze 125: .It Fl v
126: Display all files added or removed to the index.
1.6 ! schwarze 127: With a second
! 128: .Fl v ,
! 129: also show all keyswords added for each file.
1.1 schwarze 130: .It Fl W
131: Print warnings about potential problems with manual pages
132: to the standard error output.
133: .El
134: .Pp
135: If fatal parse errors are encountered while parsing, the offending file
136: is printed to stderr, omitted from the index, and the parse continues
137: with the next input file.
138: .Sh FILES
139: .Bl -tag -width Ds
140: .It Pa mandoc.db
1.5 schwarze 141: A database of manpages relative to the directory of the file.
142: This file is portable across architectures and systems, so long as the
143: manpage hierarchy it indexes does not change.
1.1 schwarze 144: .It Pa /etc/man.conf
145: The default
146: .Xr man 1
147: configuration file.
148: .El
149: .Sh EXIT STATUS
150: The
151: .Nm
152: utility exits with one of the following values:
153: .Pp
154: .Bl -tag -width Ds -compact
155: .It 0
156: No errors occurred.
157: .It 5
158: Invalid command line arguments were specified.
159: No input files have been read.
160: .It 6
161: An operating system error occurred, for example memory exhaustion or an
162: error accessing input files.
163: Such errors cause
164: .Nm
165: to exit at once, possibly in the middle of parsing or formatting a file.
166: The output databases are corrupt and should be removed.
167: .El
168: .Sh SEE ALSO
169: .Xr apropos 1 ,
170: .Xr man 1 ,
171: .Xr whatis 1 ,
172: .Xr man.conf 5
1.3 schwarze 173: .Sh HISTORY
174: A
175: .Nm
176: utility first appeared in
177: .Bx 2 .
178: It was rewritten in
179: .Xr perl 1
180: for
181: .Ox 2.7
182: and in C for
1.6 ! schwarze 183: .Ox 5.6 .
1.3 schwarze 184: .Pp
185: The
186: .Ar dir
187: argument first appeared in
188: .Nx 1.0 ;
189: the options
190: .Fl dtu
191: in
192: .Ox 2.7 ;
193: and the options
1.6 ! schwarze 194: .Fl aCnQTvW
1.3 schwarze 195: in
1.6 ! schwarze 196: .Ox 5.6 .
1.1 schwarze 197: .Sh AUTHORS
1.3 schwarze 198: .An -nosplit
199: .An Bill Joy
200: wrote the original
201: .Bx
202: .Nm
203: in February 1979,
204: .An Marc Espie
205: started the Perl version in 2000,
1.5 schwarze 206: and the current version of
207: .Nm
208: was written by
209: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
210: and
211: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .