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