Annotation of mandoc/mandocdb.8, Revision 1.4
1.4 ! kristaps 1: .\" $Id: mandocdb.8,v 1.3 2011/07/15 17:59:29 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.3 kristaps 17: .Dd $Mdocdate: July 15 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.3 kristaps 25: .Op Fl v
26: .Op Ar dir...
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.1 schwarze 45: The arguments are as follows:
46: .Bl -tag -width Ds
1.3 kristaps 47: .It Fl d Ar dir
48: Remove
49: .Ar
50: from the databases in
51: .Ar dir .
52: .It Fl u Ar dir
53: Update (remove and re-add)
54: .Ar
55: from the databases in
56: .Ar dir .
1.2 kristaps 57: .It Ar dir...
1.3 kristaps 58: Recursively add files rooted at each
1.2 kristaps 59: .Ar dir
1.3 kristaps 60: to the databases in the respective
61: .Ar dir .
1.2 kristaps 62: Existing databases are truncated.
1.3 kristaps 63: .It Fl v
64: Verbose operation.
65: Use once to display all files added or removed and twice for keywords as
66: well.
1.1 schwarze 67: .El
68: .Pp
69: By default,
70: .Nm
1.3 kristaps 71: creates databases in each
72: .Ar dir
73: using files rooted in that directory.
1.1 schwarze 74: .Pp
1.2 kristaps 75: If fatal parse errors are encountered while parsing, the offending file
76: is printed to stderr, omitted from the index, and the parse continues
77: with the next input file.
1.1 schwarze 78: .Ss Index Database
79: The index database,
80: .Pa mandoc.index ,
81: is a
82: .Xr recno 3
83: database with record values consisting of
84: .Pp
85: .Bl -enum -compact
86: .It
87: a nil-terminated filename,
88: .It
89: a nil-terminated manual section,
90: .It
91: a nil-terminated manual title,
92: .It
93: a nil-terminated architecture
94: .Pq this is not often available
95: .It
96: and a nil-terminated description.
97: .El
98: .Pp
1.3 kristaps 99: Both the manual section and description may be zero-length if the record
100: is unassigned.
1.1 schwarze 101: Entries are sequentially-numbered, but the filenames are unordered.
102: .Ss Keyword Database
103: The keyword database,
104: .Pa mandoc.db ,
105: is a
106: .Xr btree 3
107: database of nil-terminated keywords (record length is non-zero string
108: length plus one) mapping to a 8-byte binary field consisting of the
109: keyword type and source
110: .Sx Index Database
111: record number.
112: The type, a 32-bit bit-mask in host order, consists of the following
113: fields:
114: .Pp
115: .Bl -tag -width Ds -offset indent -compact
116: .It Li 0x01
117: The name of a manual page as given in the NAME section.
118: .It Li 0x02
119: A function prototype name as given in the SYNOPSIS section.
120: .It Li 0x04
121: A utility name as given in the SYNOPSIS section.
122: .It Li 0x08
123: An include file as given in the SYNOPSIS section.
124: .It Li 0x10
125: A variable name as given in the SYNOPSIS section.
126: .It Li 0x20
127: A standard as given in the STANDARDS section.
128: .It Li 0x40
129: An author as given in the AUTHORS section.
130: .It Li 0x80
131: A configuration as given in the SYNOPSIS section.
132: .It Li 0x100
133: Free-form descriptive text as given in the NAME section.
134: .It Li 0x200
135: Cross-links between manuals.
136: Listed as the link name, then a period, then the link section.
137: If the link has no section, the period terminates the string.
138: .It Li 0x400
139: Path reference as given in the FILES section.
140: .It Li 0x800
141: Environment variable as given in the ENVIRONMENT section.
142: .It Li 0x1000
143: Error codes as given in the ERRORS section.
144: .El
145: .Pp
146: The last four bytes are a host-ordered record number within the
147: .Sx Index Database .
148: .Pp
149: The
150: .Nm
151: utility is
152: .Ud
153: .Sh IMPLEMENTATION NOTES
154: The time to construct a new database pair grows linearly with the
1.3 kristaps 155: number of keywords in the input files.
1.1 schwarze 156: However, removing or updating entries with
1.3 kristaps 157: .Fl u
1.1 schwarze 158: or
1.3 kristaps 159: .Fl d ,
1.1 schwarze 160: respectively, grows as a multiple of the index length and input size.
161: .Sh FILES
162: .Bl -tag -width Ds
163: .It Pa mandoc.db
164: A
165: .Xr btree 3
166: keyword database mapping keywords to a type and file reference in
167: .Pa mandoc.index .
168: .It Pa mandoc.index
169: A
170: .Xr recno 3
171: database of indexed file-names.
172: .El
173: .Sh EXIT STATUS
174: The
175: .Nm
176: utility exits with one of the following values:
177: .Pp
178: .Bl -tag -width Ds -compact
179: .It 0
180: No errors occurred.
181: .It 5
182: Invalid command line arguments were specified.
183: No input files have been read.
184: .It 6
185: An operating system error occurred, for example memory exhaustion or an
186: error accessing input files.
187: Such errors cause
188: .Nm
189: to exit at once, possibly in the middle of parsing or formatting a file.
190: The output databases are corrupt and should be removed .
191: .El
192: .Sh SEE ALSO
1.3 kristaps 193: .Xr mandoc 1 ,
194: .Xr btree 3 ,
195: .Xr recno 3
1.1 schwarze 196: .Sh AUTHORS
197: The
198: .Nm
199: utility was written by
1.4 ! kristaps 200: .An Kristaps Dzonsons ,
! 201: .Mt kristaps@bsd.lv .
CVSweb