Annotation of src/usr.bin/mandoc/makewhatis.8, Revision 1.15
1.15 ! schwarze 1: .\" $OpenBSD: makewhatis.8,v 1.14 2017/05/17 22:26:52 schwarze Exp $
1.1 schwarze 2: .\"
1.5 schwarze 3: .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
1.13 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.15 ! schwarze 18: .Dd $Mdocdate: May 17 2017 $
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.8 schwarze 26: .Op Fl aDnpQ
1.6 schwarze 27: .Op Fl T Cm utf8
1.1 schwarze 28: .Op Fl C Ar file
29: .Nm
1.8 schwarze 30: .Op Fl aDnpQ
1.6 schwarze 31: .Op Fl T Cm utf8
1.1 schwarze 32: .Ar dir ...
33: .Nm
1.8 schwarze 34: .Op Fl DnpQ
1.6 schwarze 35: .Op Fl T Cm utf8
1.1 schwarze 36: .Fl d Ar dir
37: .Op Ar
38: .Nm
1.8 schwarze 39: .Op Fl Dnp
1.6 schwarze 40: .Op Fl T Cm utf8
1.1 schwarze 41: .Fl u Ar dir
42: .Op Ar
43: .Nm
1.10 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
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
1.15 ! schwarze 55: .Xr man 1 .
1.1 schwarze 56: .Pp
57: By default,
58: .Nm
1.5 schwarze 59: creates a database in each
1.1 schwarze 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
1.5 schwarze 73: in that directory.
74: Existing databases are replaced.
1.14 schwarze 75: If a directory contains no manual pages, no database is created in that
76: directory.
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.
1.7 schwarze 95: .It Fl D
96: Display all files added or removed to the index.
97: With a second
98: .Fl D ,
1.11 schwarze 99: also show all keywords added for each file.
1.1 schwarze 100: .It Fl d Ar dir
101: Merge (remove and re-add)
102: .Ar
103: to the database in
1.5 schwarze 104: .Ar dir .
105: .It Fl n
1.9 schwarze 106: Do not create or modify any database; scan and parse only,
107: and print manual page names and descriptions to standard output.
1.8 schwarze 108: .It Fl p
109: Print warnings about potential problems with manual pages
110: to the standard error output.
1.6 schwarze 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.
1.1 schwarze 117: .It Fl t Ar
118: Check the given
119: .Ar files
120: for potential problems.
121: Implies
1.5 schwarze 122: .Fl a ,
123: .Fl n ,
1.1 schwarze 124: and
1.8 schwarze 125: .Fl p .
1.1 schwarze 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
1.5 schwarze 132: .Ar dir .
1.14 schwarze 133: If that causes the database to become empty, also delete the database file.
1.1 schwarze 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.
1.13 schwarze 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
1.1 schwarze 149: .Sh FILES
150: .Bl -tag -width Ds
151: .It Pa mandoc.db
1.5 schwarze 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.
1.1 schwarze 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
1.3 schwarze 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
1.6 schwarze 194: .Ox 5.6 .
1.3 schwarze 195: .Pp
196: The
197: .Ar dir
198: argument first appeared in
199: .Nx 1.0 ;
200: the options
1.8 schwarze 201: .Fl dpt
1.3 schwarze 202: in
203: .Ox 2.7 ;
1.8 schwarze 204: the option
205: .Fl u
206: in
207: .Ox 3.4 ;
1.3 schwarze 208: and the options
1.8 schwarze 209: .Fl aCDnQT
1.3 schwarze 210: in
1.6 schwarze 211: .Ox 5.6 .
1.1 schwarze 212: .Sh AUTHORS
1.3 schwarze 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,
1.5 schwarze 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 .