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