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