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