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