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