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