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