Annotation of mandoc/mandocdb.8, Revision 1.11
1.11 ! kristaps 1: .\" $Id: mandocdb.8,v 1.10 2011/12/01 21:05:49 kristaps 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.11 ! kristaps 17: .Dd $Mdocdate: December 1 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.7 schwarze 25: .Op Fl av
1.8 schwarze 26: .Op Ar dir ...
1.3 kristaps 27: .Nm
28: .Op Fl v
29: .Fl d Ar dir
30: .Op Ar
31: .Nm
32: .Op Fl v
33: .Fl u Ar dir
34: .Op Ar
1.1 schwarze 35: .Sh DESCRIPTION
36: The
37: .Nm
38: utility extracts keywords from
39: .Ux
1.3 kristaps 40: manuals and indexes them in a
41: .Sx Keyword Database
42: and
43: .Sx Index Database
44: for fast retrieval.
1.7 schwarze 45: .Pp
1.8 schwarze 46: By default,
47: .Nm
48: creates databases in each
49: .Ar dir
50: using the files
51: .Sm off
52: .Sy man Ar section Li /
53: .Op Ar arch Li /
54: .Ar title . section
55: .Sm on
56: and
57: .Sm off
58: .Sy cat Ar section Li /
59: .Op Ar arch Li /
60: .Ar title . Sy 0
61: .Sm on
62: in that directory;
63: existing databases are truncated.
64: If
65: .Ar dir
66: is not provided,
67: .Nm
68: uses the default paths stipulated by
69: .Xr man 1 .
70: .Pp
1.1 schwarze 71: The arguments are as follows:
72: .Bl -tag -width Ds
1.7 schwarze 73: .It Fl a
74: Use all directories and files found below
75: .Ar dir ... .
1.3 kristaps 76: .It Fl d Ar dir
1.5 kristaps 77: Merge (remove and re-add)
1.3 kristaps 78: .Ar
1.8 schwarze 79: to the database in
80: .Ar dir
81: without truncating it.
1.3 kristaps 82: .It Fl u Ar dir
1.5 kristaps 83: Remove
1.3 kristaps 84: .Ar
1.8 schwarze 85: from the database in
1.2 kristaps 86: .Ar dir
1.8 schwarze 87: without truncating it.
1.3 kristaps 88: .It Fl v
1.10 kristaps 89: Display all files added or removed to the index.
1.1 schwarze 90: .El
91: .Pp
1.2 kristaps 92: If fatal parse errors are encountered while parsing, the offending file
93: is printed to stderr, omitted from the index, and the parse continues
94: with the next input file.
1.1 schwarze 95: .Ss Index Database
96: The index database,
97: .Pa mandoc.index ,
98: is a
99: .Xr recno 3
100: database with record values consisting of
101: .Pp
102: .Bl -enum -compact
103: .It
1.8 schwarze 104: the string
105: .Cm mdoc ,
106: .Cm man ,
107: or
108: .Cm cat
1.9 kristaps 109: to indicate the file type
110: .Po
111: file in
112: .Xr mdoc 7 ,
113: .Xr man 7 ,
114: and post-formatted, respectively
115: .Pc ,
1.1 schwarze 116: .It
1.8 schwarze 117: the filename,
1.1 schwarze 118: .It
1.8 schwarze 119: the manual section,
1.1 schwarze 120: .It
1.8 schwarze 121: the manual title,
1.1 schwarze 122: .It
1.8 schwarze 123: the architecture
124: .Pq often empty ,
125: .It
126: and the description.
1.1 schwarze 127: .El
128: .Pp
1.8 schwarze 129: Each of the above is NUL-terminated.
130: .Pp
1.3 kristaps 131: Both the manual section and description may be zero-length if the record
132: is unassigned.
1.1 schwarze 133: Entries are sequentially-numbered, but the filenames are unordered.
134: .Ss Keyword Database
135: The keyword database,
136: .Pa mandoc.db ,
137: is a
138: .Xr btree 3
1.8 schwarze 139: database of NUL-terminated keywords (record length is non-zero string
1.11 ! kristaps 140: length plus one) mapping to a 12-byte binary field consisting of the
! 141: 64-bit keyword type and 32-bit source
1.1 schwarze 142: .Sx Index Database
1.11 ! kristaps 143: record number, both in network-byte order.
! 144: The typet bit-mask consists of the following
1.9 kristaps 145: values mapping into
146: .Xr mdoc 7
147: macro identifiers:
148: .Pp
149: .Bl -column "x0x0000000000000001ULLx" "xLix" -offset indent -compact
150: .It Li 0x0000000000000001ULL Ta \&An
151: .It Li 0x0000000000000002ULL Ta \&Ar
152: .It Li 0x0000000000000004ULL Ta \&At
153: .It Li 0x0000000000000008ULL Ta \&Bsx
154: .It Li 0x0000000000000010ULL Ta \&Bx
155: .It Li 0x0000000000000020ULL Ta \&Cd
156: .It Li 0x0000000000000040ULL Ta \&Cm
157: .It Li 0x0000000000000080ULL Ta \&Dv
158: .It Li 0x0000000000000100ULL Ta \&Dx
159: .It Li 0x0000000000000200ULL Ta \&Em
160: .It Li 0x0000000000000400ULL Ta \&Er
161: .It Li 0x0000000000000800ULL Ta \&Ev
162: .It Li 0x0000000000001000ULL Ta \&Fa
163: .It Li 0x0000000000002000ULL Ta \&Fl
164: .It Li 0x0000000000004000ULL Ta \&Fn
165: .It Li 0x0000000000008000ULL Ta \&Ft
166: .It Li 0x0000000000010000ULL Ta \&Fx
167: .It Li 0x0000000000020000ULL Ta \&Ic
168: .It Li 0x0000000000040000ULL Ta \&In
169: .It Li 0x0000000000080000ULL Ta \&Lb
170: .It Li 0x0000000000100000ULL Ta \&Li
171: .It Li 0x0000000000200000ULL Ta \&Lk
172: .It Li 0x0000000000400000ULL Ta \&Ms
173: .It Li 0x0000000000800000ULL Ta \&Mt
174: .It Li 0x0000000001000000ULL Ta \&Nd
175: .It Li 0x0000000002000000ULL Ta \&Nm
176: .It Li 0x0000000004000000ULL Ta \&Nx
177: .It Li 0x0000000008000000ULL Ta \&Ox
178: .It Li 0x0000000010000000ULL Ta \&Pa
179: .It Li 0x0000000020000000ULL Ta \&Rs
180: .It Li 0x0000000040000000ULL Ta \&Sh
181: .It Li 0x0000000080000000ULL Ta \&Ss
182: .It Li 0x0000000100000000ULL Ta \&St
183: .It Li 0x0000000200000000ULL Ta \&Sy
184: .It Li 0x0000000400000000ULL Ta \&Tn
185: .It Li 0x0000000800000000ULL Ta \&Va
186: .It Li 0x0000001000000000ULL Ta \&Vt
187: .It Li 0x0000002000000000ULL Ta \&Xr
1.1 schwarze 188: .El
189: .Pp
190: The last four bytes are a host-ordered record number within the
191: .Sx Index Database .
192: .Sh IMPLEMENTATION NOTES
193: The time to construct a new database pair grows linearly with the
1.3 kristaps 194: number of keywords in the input files.
1.1 schwarze 195: However, removing or updating entries with
1.3 kristaps 196: .Fl u
1.1 schwarze 197: or
1.3 kristaps 198: .Fl d ,
1.1 schwarze 199: respectively, grows as a multiple of the index length and input size.
200: .Sh FILES
201: .Bl -tag -width Ds
202: .It Pa mandoc.db
203: A
204: .Xr btree 3
205: keyword database mapping keywords to a type and file reference in
206: .Pa mandoc.index .
207: .It Pa mandoc.index
208: A
209: .Xr recno 3
210: database of indexed file-names.
211: .El
212: .Sh EXIT STATUS
213: The
214: .Nm
215: utility exits with one of the following values:
216: .Pp
217: .Bl -tag -width Ds -compact
218: .It 0
219: No errors occurred.
220: .It 5
221: Invalid command line arguments were specified.
222: No input files have been read.
223: .It 6
224: An operating system error occurred, for example memory exhaustion or an
225: error accessing input files.
226: Such errors cause
227: .Nm
228: to exit at once, possibly in the middle of parsing or formatting a file.
229: The output databases are corrupt and should be removed .
1.10 kristaps 230: .El
231: .Sh DIAGNOSTICS
232: If the following errors occur, the
233: .Nm
234: databases should be rebuilt.
235: .Bl -diag
236: .It "%s: Corrupt database"
237: The keyword database file indicated by
238: .Pa %s
239: is unreadable.
240: .It "%s: Corrupt index"
241: The index database file indicated by
242: .Pa %s
243: is unreadable.
244: .It "%s: Path too long"
245: The file
246: .Pa %s
247: is too long.
248: This usually indicates database corruption or invalid command-line
249: arguments.
1.1 schwarze 250: .El
251: .Sh SEE ALSO
1.6 kristaps 252: .Xr man 1 ,
1.3 kristaps 253: .Xr btree 3 ,
254: .Xr recno 3
1.1 schwarze 255: .Sh AUTHORS
256: The
257: .Nm
258: utility was written by
1.4 kristaps 259: .An Kristaps Dzonsons ,
260: .Mt kristaps@bsd.lv .
CVSweb