Annotation of mandoc/mandocdb.8, Revision 1.2
1.2 ! kristaps 1: .\" $Id: mandocdb.8,v 1.1 2011/07/14 14:36:37 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: .\"
17: .Dd $Mdocdate: July 14 2011 $
18: .Dt MANDOCDB 8
19: .Os
20: .Sh NAME
21: .Nm mandocdb
22: .Nd index UNIX manuals
23: .Sh SYNOPSIS
24: .Nm
1.2 ! kristaps 25: .Ar dir...
1.1 schwarze 26: .Sh DESCRIPTION
27: The
28: .Nm
29: utility extracts keywords from
30: .Ux
31: manuals and indexes them for fast retrieval.
32: The arguments are as follows:
33: .Bl -tag -width Ds
1.2 ! kristaps 34: .It Ar dir...
! 35: Recursively scan for
1.1 schwarze 36: .Xr mdoc 7
1.2 ! kristaps 37: and
1.1 schwarze 38: .Xr man 7
39: .Ux
1.2 ! kristaps 40: manual files in each
! 41: .Ar dir
! 42: directory.
! 43: .Sx Index Database
! 44: and
! 45: .Sx Keyword Database
! 46: files are installed in each
! 47: .Ar dir
! 48: directory.
! 49: Existing databases are truncated.
1.1 schwarze 50: .El
51: .Pp
52: By default,
53: .Nm
1.2 ! kristaps 54: does nothing: the
! 55: .Ar dir...
! 56: invocation must be used.
1.1 schwarze 57: .Pp
1.2 ! kristaps 58: If fatal parse errors are encountered while parsing, the offending file
! 59: is printed to stderr, omitted from the index, and the parse continues
! 60: with the next input file.
1.1 schwarze 61: .Ss Index Database
62: The index database,
63: .Pa mandoc.index ,
64: is a
65: .Xr recno 3
66: database with record values consisting of
67: .Pp
68: .Bl -enum -compact
69: .It
70: a nil-terminated filename,
71: .It
72: a nil-terminated manual section,
73: .It
74: a nil-terminated manual title,
75: .It
76: a nil-terminated architecture
77: .Pq this is not often available
78: .It
79: and a nil-terminated description.
80: .El
81: .Pp
82: Both the manual section and description may be zero-length.
83: Entries are sequentially-numbered, but the filenames are unordered.
84: .Ss Keyword Database
85: The keyword database,
86: .Pa mandoc.db ,
87: is a
88: .Xr btree 3
89: database of nil-terminated keywords (record length is non-zero string
90: length plus one) mapping to a 8-byte binary field consisting of the
91: keyword type and source
92: .Sx Index Database
93: record number.
94: The type, a 32-bit bit-mask in host order, consists of the following
95: fields:
96: .Pp
97: .Bl -tag -width Ds -offset indent -compact
98: .It Li 0x01
99: The name of a manual page as given in the NAME section.
100: .It Li 0x02
101: A function prototype name as given in the SYNOPSIS section.
102: .It Li 0x04
103: A utility name as given in the SYNOPSIS section.
104: .It Li 0x08
105: An include file as given in the SYNOPSIS section.
106: .It Li 0x10
107: A variable name as given in the SYNOPSIS section.
108: .It Li 0x20
109: A standard as given in the STANDARDS section.
110: .It Li 0x40
111: An author as given in the AUTHORS section.
112: .It Li 0x80
113: A configuration as given in the SYNOPSIS section.
114: .It Li 0x100
115: Free-form descriptive text as given in the NAME section.
116: .It Li 0x200
117: Cross-links between manuals.
118: Listed as the link name, then a period, then the link section.
119: If the link has no section, the period terminates the string.
120: .It Li 0x400
121: Path reference as given in the FILES section.
122: .It Li 0x800
123: Environment variable as given in the ENVIRONMENT section.
124: .It Li 0x1000
125: Error codes as given in the ERRORS section.
126: .El
127: .Pp
128: The last four bytes are a host-ordered record number within the
129: .Sx Index Database .
130: .Pp
131: The
132: .Nm
133: utility is
134: .Ud
135: .Sh IMPLEMENTATION NOTES
136: The time to construct a new database pair grows linearly with the
137: number of keywords in the input.
138: However, removing or updating entries with
139: .Fl r
140: or
141: .Fl u ,
142: respectively, grows as a multiple of the index length and input size.
143: .Sh FILES
144: .Bl -tag -width Ds
145: .It Pa mandoc.db
146: A
147: .Xr btree 3
148: keyword database mapping keywords to a type and file reference in
149: .Pa mandoc.index .
150: .It Pa mandoc.index
151: A
152: .Xr recno 3
153: database of indexed file-names.
154: .El
155: .Sh EXIT STATUS
156: The
157: .Nm
158: utility exits with one of the following values:
159: .Pp
160: .Bl -tag -width Ds -compact
161: .It 0
162: No errors occurred.
163: .It 5
164: Invalid command line arguments were specified.
165: No input files have been read.
166: .It 6
167: An operating system error occurred, for example memory exhaustion or an
168: error accessing input files.
169: Such errors cause
170: .Nm
171: to exit at once, possibly in the middle of parsing or formatting a file.
172: The output databases are corrupt and should be removed .
173: .El
174: .Sh SEE ALSO
175: .Xr mandoc 1
176: .Sh AUTHORS
177: The
178: .Nm
179: utility was written by
180: .An Kristaps Dzonsons Aq 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