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