Annotation of mandoc/mandocdb.8, Revision 1.17.2.2
1.17.2.2! schwarze 1: .\" $Id: mandocdb.8,v 1.17.2.1 2013/09/18 01:04:07 schwarze Exp $
1.1 schwarze 2: .\"
1.17.2.2! 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.17.2.2! schwarze 18: .Dd $Mdocdate: September 18 2013 $
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.15 schwarze 26: .Op Fl avW
1.12 schwarze 27: .Op Fl C Ar file
28: .Nm
1.15 schwarze 29: .Op Fl avW
1.12 schwarze 30: .Ar dir ...
1.3 kristaps 31: .Nm
1.15 schwarze 32: .Op Fl vW
1.3 kristaps 33: .Fl d Ar dir
34: .Op Ar
35: .Nm
1.15 schwarze 36: .Op Fl vW
1.3 kristaps 37: .Fl u Ar dir
38: .Op Ar
1.15 schwarze 39: .Nm
40: .Fl t Ar
1.1 schwarze 41: .Sh DESCRIPTION
42: The
43: .Nm
44: utility extracts keywords from
45: .Ux
1.3 kristaps 46: manuals and indexes them in a
47: .Sx Keyword Database
48: and
49: .Sx Index Database
1.17 schwarze 50: for fast retrieval by
51: .Xr apropos 1 ,
52: .Xr whatis 1 ,
53: and
54: .Xr man 1 Ns 's
55: .Fl k
56: option.
1.7 schwarze 57: .Pp
1.8 schwarze 58: By default,
59: .Nm
60: creates databases in each
61: .Ar dir
62: using the files
63: .Sm off
64: .Sy man Ar section Li /
65: .Op Ar arch Li /
66: .Ar title . section
67: .Sm on
68: and
69: .Sm off
70: .Sy cat Ar section Li /
71: .Op Ar arch Li /
72: .Ar title . Sy 0
73: .Sm on
1.17.2.2! schwarze 74: in that directory.
! 75: Existing databases are replaced.
1.8 schwarze 76: If
77: .Ar dir
78: is not provided,
79: .Nm
80: uses the default paths stipulated by
1.17.2.2! schwarze 81: .Xr manpath 1 ,
! 82: or
! 83: .Xr man.conf 5 .
1.8 schwarze 84: .Pp
1.1 schwarze 85: The arguments are as follows:
1.12 schwarze 86: .Bl -tag -width "-C file"
1.7 schwarze 87: .It Fl a
88: Use all directories and files found below
89: .Ar dir ... .
1.12 schwarze 90: .It Fl C Ar file
91: Specify an alternative configuration
92: .Ar file
93: in
94: .Xr man.conf 5
95: format.
1.3 kristaps 96: .It Fl d Ar dir
1.5 kristaps 97: Merge (remove and re-add)
1.3 kristaps 98: .Ar
1.8 schwarze 99: to the database in
100: .Ar dir
101: without truncating it.
1.15 schwarze 102: .It Fl t Ar
103: Check the given
104: .Ar files
105: for potential problems.
106: No databases are modified.
107: Implies
108: .Fl a
109: and
110: .Fl W .
111: All diagnostic messages are printed to the standard output;
112: the standard error output is not used.
1.3 kristaps 113: .It Fl u Ar dir
1.5 kristaps 114: Remove
1.3 kristaps 115: .Ar
1.8 schwarze 116: from the database in
1.2 kristaps 117: .Ar dir
1.8 schwarze 118: without truncating it.
1.3 kristaps 119: .It Fl v
1.10 kristaps 120: Display all files added or removed to the index.
1.15 schwarze 121: .It Fl W
122: Print warnings about potential problems with manual pages
123: to the standard error output.
1.1 schwarze 124: .El
125: .Pp
1.2 kristaps 126: If fatal parse errors are encountered while parsing, the offending file
127: is printed to stderr, omitted from the index, and the parse continues
128: with the next input file.
1.1 schwarze 129: .Ss Index Database
130: The index database,
1.17.2.1 schwarze 131: .Pa mandoc.index ,
1.1 schwarze 132: is a
133: .Xr recno 3
134: database with record values consisting of
135: .Pp
136: .Bl -enum -compact
137: .It
1.14 kristaps 138: the character
139: .Cm d ,
140: .Cm a ,
1.8 schwarze 141: or
1.14 kristaps 142: .Cm c
1.9 kristaps 143: to indicate the file type
144: .Po
145: .Xr mdoc 7 ,
146: .Xr man 7 ,
147: and post-formatted, respectively
148: .Pc ,
1.1 schwarze 149: .It
1.13 kristaps 150: the filename relative to the databases' path,
1.1 schwarze 151: .It
1.8 schwarze 152: the manual section,
1.1 schwarze 153: .It
1.8 schwarze 154: the manual title,
1.1 schwarze 155: .It
1.8 schwarze 156: the architecture
157: .Pq often empty ,
158: .It
159: and the description.
1.1 schwarze 160: .El
161: .Pp
1.8 schwarze 162: Each of the above is NUL-terminated.
163: .Pp
1.14 kristaps 164: If the record value is zero-length, it is unassigned.
1.1 schwarze 165: .Ss Keyword Database
166: The keyword database,
1.17.2.1 schwarze 167: .Pa mandoc.db ,
1.1 schwarze 168: is a
169: .Xr btree 3
1.8 schwarze 170: database of NUL-terminated keywords (record length is non-zero string
1.17 schwarze 171: length plus one) mapping to a 16-byte binary field consisting of the
172: 64-bit keyword type and the 64-bit
1.1 schwarze 173: .Sx Index Database
1.11 kristaps 174: record number, both in network-byte order.
1.17 schwarze 175: .Pp
1.12 schwarze 176: The type bit-mask consists of the following
1.9 kristaps 177: values mapping into
178: .Xr mdoc 7
179: macro identifiers:
180: .Pp
181: .Bl -column "x0x0000000000000001ULLx" "xLix" -offset indent -compact
182: .It Li 0x0000000000000001ULL Ta \&An
183: .It Li 0x0000000000000002ULL Ta \&Ar
184: .It Li 0x0000000000000004ULL Ta \&At
185: .It Li 0x0000000000000008ULL Ta \&Bsx
186: .It Li 0x0000000000000010ULL Ta \&Bx
187: .It Li 0x0000000000000020ULL Ta \&Cd
188: .It Li 0x0000000000000040ULL Ta \&Cm
189: .It Li 0x0000000000000080ULL Ta \&Dv
190: .It Li 0x0000000000000100ULL Ta \&Dx
191: .It Li 0x0000000000000200ULL Ta \&Em
192: .It Li 0x0000000000000400ULL Ta \&Er
193: .It Li 0x0000000000000800ULL Ta \&Ev
194: .It Li 0x0000000000001000ULL Ta \&Fa
195: .It Li 0x0000000000002000ULL Ta \&Fl
196: .It Li 0x0000000000004000ULL Ta \&Fn
197: .It Li 0x0000000000008000ULL Ta \&Ft
198: .It Li 0x0000000000010000ULL Ta \&Fx
199: .It Li 0x0000000000020000ULL Ta \&Ic
200: .It Li 0x0000000000040000ULL Ta \&In
201: .It Li 0x0000000000080000ULL Ta \&Lb
202: .It Li 0x0000000000100000ULL Ta \&Li
203: .It Li 0x0000000000200000ULL Ta \&Lk
204: .It Li 0x0000000000400000ULL Ta \&Ms
205: .It Li 0x0000000000800000ULL Ta \&Mt
206: .It Li 0x0000000001000000ULL Ta \&Nd
207: .It Li 0x0000000002000000ULL Ta \&Nm
208: .It Li 0x0000000004000000ULL Ta \&Nx
209: .It Li 0x0000000008000000ULL Ta \&Ox
210: .It Li 0x0000000010000000ULL Ta \&Pa
211: .It Li 0x0000000020000000ULL Ta \&Rs
212: .It Li 0x0000000040000000ULL Ta \&Sh
213: .It Li 0x0000000080000000ULL Ta \&Ss
214: .It Li 0x0000000100000000ULL Ta \&St
215: .It Li 0x0000000200000000ULL Ta \&Sy
216: .It Li 0x0000000400000000ULL Ta \&Tn
217: .It Li 0x0000000800000000ULL Ta \&Va
218: .It Li 0x0000001000000000ULL Ta \&Vt
219: .It Li 0x0000002000000000ULL Ta \&Xr
1.1 schwarze 220: .El
221: .Sh IMPLEMENTATION NOTES
222: The time to construct a new database pair grows linearly with the
1.3 kristaps 223: number of keywords in the input files.
1.1 schwarze 224: However, removing or updating entries with
1.3 kristaps 225: .Fl u
1.1 schwarze 226: or
1.3 kristaps 227: .Fl d ,
1.1 schwarze 228: respectively, grows as a multiple of the index length and input size.
229: .Sh FILES
230: .Bl -tag -width Ds
1.17.2.1 schwarze 231: .It Pa mandoc.db
1.1 schwarze 232: A
233: .Xr btree 3
234: keyword database mapping keywords to a type and file reference in
1.17.2.1 schwarze 235: .Pa mandoc.index .
236: .It Pa mandoc.index
1.1 schwarze 237: A
238: .Xr recno 3
239: database of indexed file-names.
1.12 schwarze 240: .It Pa /etc/man.conf
241: The default
242: .Xr man 1
243: configuration file.
1.1 schwarze 244: .El
245: .Sh EXIT STATUS
246: The
247: .Nm
248: utility exits with one of the following values:
249: .Pp
250: .Bl -tag -width Ds -compact
251: .It 0
252: No errors occurred.
253: .It 5
254: Invalid command line arguments were specified.
255: No input files have been read.
256: .It 6
257: An operating system error occurred, for example memory exhaustion or an
258: error accessing input files.
259: Such errors cause
260: .Nm
261: to exit at once, possibly in the middle of parsing or formatting a file.
1.17 schwarze 262: The output databases are corrupt and should be removed.
1.10 kristaps 263: .El
264: .Sh DIAGNOSTICS
265: If the following errors occur, the
266: .Nm
267: databases should be rebuilt.
268: .Bl -diag
269: .It "%s: Corrupt database"
270: The keyword database file indicated by
271: .Pa %s
272: is unreadable.
273: .It "%s: Corrupt index"
274: The index database file indicated by
275: .Pa %s
276: is unreadable.
277: .It "%s: Path too long"
278: The file
279: .Pa %s
280: is too long.
281: This usually indicates database corruption or invalid command-line
282: arguments.
1.1 schwarze 283: .El
284: .Sh SEE ALSO
1.12 schwarze 285: .Xr apropos 1 ,
1.6 kristaps 286: .Xr man 1 ,
1.12 schwarze 287: .Xr whatis 1 ,
1.3 kristaps 288: .Xr btree 3 ,
1.12 schwarze 289: .Xr recno 3 ,
290: .Xr man.conf 5
1.17.2.1 schwarze 291: .Sh HISTORY
292: A
293: .Nm makewhatis
294: utility first appeared in
295: .Bx 2 .
296: It was rewritten in
297: .Xr perl 1
298: for
299: .Ox 2.7
300: and in C for
301: .Ox 5.1 .
302: .Pp
1.1 schwarze 303: The
1.17.2.1 schwarze 304: .Ar dir
305: argument first appeared in
306: .Nx 1.0 ;
307: the options
308: .Fl dtu
309: in
310: .Ox 2.7 ;
311: and the options
312: .Fl aCvW
313: in
314: .Ox 5.1 .
315: .Sh AUTHORS
316: .An -nosplit
317: .An Bill Joy
318: wrote the original
319: .Bx
320: .Nm makewhatis
321: in February 1979,
322: .An Marc Espie
323: started the Perl version in 2000,
324: and the current version of
1.1 schwarze 325: .Nm
1.17.2.1 schwarze 326: was written by
1.17.2.2! schwarze 327: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
! 328: and
! 329: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mandocdb.8 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc