Annotation of mandoc/mandocdb.8, Revision 1.12
1.12 ! schwarze 1: .\" $Id: mandocdb.8,v 1.11 2011/12/02 00:21:56 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.12 ! schwarze 17: .Dd $Mdocdate: December 2 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.8 schwarze 113: the string
114: .Cm mdoc ,
115: .Cm man ,
116: or
117: .Cm cat
1.9 kristaps 118: to indicate the file type
119: .Po
120: file in
121: .Xr mdoc 7 ,
122: .Xr man 7 ,
123: and post-formatted, respectively
124: .Pc ,
1.1 schwarze 125: .It
1.8 schwarze 126: the filename,
1.1 schwarze 127: .It
1.8 schwarze 128: the manual section,
1.1 schwarze 129: .It
1.8 schwarze 130: the manual title,
1.1 schwarze 131: .It
1.8 schwarze 132: the architecture
133: .Pq often empty ,
134: .It
135: and the description.
1.1 schwarze 136: .El
137: .Pp
1.8 schwarze 138: Each of the above is NUL-terminated.
139: .Pp
1.3 kristaps 140: Both the manual section and description may be zero-length if the record
141: is unassigned.
1.1 schwarze 142: Entries are sequentially-numbered, but the filenames are unordered.
143: .Ss Keyword Database
144: The keyword database,
145: .Pa mandoc.db ,
146: is a
147: .Xr btree 3
1.8 schwarze 148: database of NUL-terminated keywords (record length is non-zero string
1.11 kristaps 149: length plus one) mapping to a 12-byte binary field consisting of the
150: 64-bit keyword type and 32-bit source
1.1 schwarze 151: .Sx Index Database
1.11 kristaps 152: record number, both in network-byte order.
1.12 ! schwarze 153: The type bit-mask consists of the following
1.9 kristaps 154: values mapping into
155: .Xr mdoc 7
156: macro identifiers:
157: .Pp
158: .Bl -column "x0x0000000000000001ULLx" "xLix" -offset indent -compact
159: .It Li 0x0000000000000001ULL Ta \&An
160: .It Li 0x0000000000000002ULL Ta \&Ar
161: .It Li 0x0000000000000004ULL Ta \&At
162: .It Li 0x0000000000000008ULL Ta \&Bsx
163: .It Li 0x0000000000000010ULL Ta \&Bx
164: .It Li 0x0000000000000020ULL Ta \&Cd
165: .It Li 0x0000000000000040ULL Ta \&Cm
166: .It Li 0x0000000000000080ULL Ta \&Dv
167: .It Li 0x0000000000000100ULL Ta \&Dx
168: .It Li 0x0000000000000200ULL Ta \&Em
169: .It Li 0x0000000000000400ULL Ta \&Er
170: .It Li 0x0000000000000800ULL Ta \&Ev
171: .It Li 0x0000000000001000ULL Ta \&Fa
172: .It Li 0x0000000000002000ULL Ta \&Fl
173: .It Li 0x0000000000004000ULL Ta \&Fn
174: .It Li 0x0000000000008000ULL Ta \&Ft
175: .It Li 0x0000000000010000ULL Ta \&Fx
176: .It Li 0x0000000000020000ULL Ta \&Ic
177: .It Li 0x0000000000040000ULL Ta \&In
178: .It Li 0x0000000000080000ULL Ta \&Lb
179: .It Li 0x0000000000100000ULL Ta \&Li
180: .It Li 0x0000000000200000ULL Ta \&Lk
181: .It Li 0x0000000000400000ULL Ta \&Ms
182: .It Li 0x0000000000800000ULL Ta \&Mt
183: .It Li 0x0000000001000000ULL Ta \&Nd
184: .It Li 0x0000000002000000ULL Ta \&Nm
185: .It Li 0x0000000004000000ULL Ta \&Nx
186: .It Li 0x0000000008000000ULL Ta \&Ox
187: .It Li 0x0000000010000000ULL Ta \&Pa
188: .It Li 0x0000000020000000ULL Ta \&Rs
189: .It Li 0x0000000040000000ULL Ta \&Sh
190: .It Li 0x0000000080000000ULL Ta \&Ss
191: .It Li 0x0000000100000000ULL Ta \&St
192: .It Li 0x0000000200000000ULL Ta \&Sy
193: .It Li 0x0000000400000000ULL Ta \&Tn
194: .It Li 0x0000000800000000ULL Ta \&Va
195: .It Li 0x0000001000000000ULL Ta \&Vt
196: .It Li 0x0000002000000000ULL Ta \&Xr
1.1 schwarze 197: .El
198: .Pp
199: The last four bytes are a host-ordered record number within the
200: .Sx Index Database .
201: .Sh IMPLEMENTATION NOTES
202: The time to construct a new database pair grows linearly with the
1.3 kristaps 203: number of keywords in the input files.
1.1 schwarze 204: However, removing or updating entries with
1.3 kristaps 205: .Fl u
1.1 schwarze 206: or
1.3 kristaps 207: .Fl d ,
1.1 schwarze 208: respectively, grows as a multiple of the index length and input size.
209: .Sh FILES
210: .Bl -tag -width Ds
211: .It Pa mandoc.db
212: A
213: .Xr btree 3
214: keyword database mapping keywords to a type and file reference in
215: .Pa mandoc.index .
216: .It Pa mandoc.index
217: A
218: .Xr recno 3
219: database of indexed file-names.
1.12 ! schwarze 220: .It Pa /etc/man.conf
! 221: The default
! 222: .Xr man 1
! 223: configuration file.
1.1 schwarze 224: .El
225: .Sh EXIT STATUS
226: The
227: .Nm
228: utility exits with one of the following values:
229: .Pp
230: .Bl -tag -width Ds -compact
231: .It 0
232: No errors occurred.
233: .It 5
234: Invalid command line arguments were specified.
235: No input files have been read.
236: .It 6
237: An operating system error occurred, for example memory exhaustion or an
238: error accessing input files.
239: Such errors cause
240: .Nm
241: to exit at once, possibly in the middle of parsing or formatting a file.
242: The output databases are corrupt and should be removed .
1.10 kristaps 243: .El
244: .Sh DIAGNOSTICS
245: If the following errors occur, the
246: .Nm
247: databases should be rebuilt.
248: .Bl -diag
249: .It "%s: Corrupt database"
250: The keyword database file indicated by
251: .Pa %s
252: is unreadable.
253: .It "%s: Corrupt index"
254: The index database file indicated by
255: .Pa %s
256: is unreadable.
257: .It "%s: Path too long"
258: The file
259: .Pa %s
260: is too long.
261: This usually indicates database corruption or invalid command-line
262: arguments.
1.1 schwarze 263: .El
264: .Sh SEE ALSO
1.12 ! schwarze 265: .Xr apropos 1 ,
1.6 kristaps 266: .Xr man 1 ,
1.12 ! schwarze 267: .Xr whatis 1 ,
1.3 kristaps 268: .Xr btree 3 ,
1.12 ! schwarze 269: .Xr recno 3 ,
! 270: .Xr man.conf 5
1.1 schwarze 271: .Sh AUTHORS
272: The
273: .Nm
274: utility was written by
1.4 kristaps 275: .An Kristaps Dzonsons ,
276: .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