Annotation of mandoc/makewhatis.1, Revision 1.5
1.5 ! kristaps 1: .\" $Id: makewhatis.1,v 1.4 2011/06/21 13:09:19 kristaps Exp $
1.1 kristaps 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 ! kristaps 17: .Dd $Mdocdate: June 21 2011 $
1.2 kristaps 18: .Dt MAKEWHATIS 1
1.1 kristaps 19: .Os
20: .Sh NAME
21: .Nm makewhatis
22: .Nd index UNIX manuals
23: .Sh SYNOPSIS
24: .Nm
25: .Op Fl d Ar dir
26: .Ar
27: .Sh DESCRIPTION
28: The
29: .Nm
30: utility extracts keywords from
31: .Ux
32: manuals and indexes them for fast retrieval.
33: The arguments are as follows:
34: .Bl -tag -width Ds
35: .It Fl d Ar dir
36: The directory into which to write the keyword and index databases.
37: .It Ar
38: Read input from zero or more files in
39: .Xr mdoc 7
40: or
41: .Xr man 7
42: .Ux
43: manual format.
44: .El
45: .Pp
46: By default,
47: .Nm
48: constructs the
49: .Sx Index Database
50: and
51: .Sx Keyword Database
52: in the current working directory.
53: .Pp
54: If fatal parse errors are encountered, the offending file is printed to
55: stderr, omitted from the index, and the parse continues with the next
56: input file.
57: .Ss Index Database
58: The index database,
59: .Pa mandoc.index ,
60: is a
61: .Xr recno 3
62: database with record values consisting of
63: .Pp
64: .Bl -enum -compact
65: .It
66: a nil-terminated filename,
67: .It
68: a nil-terminated manual section,
69: .It
70: a nil-terminated manual title,
71: .It
72: a nil-terminated architecture
73: .Pq this is not often available
74: .It
75: and a nil-terminated description.
76: .El
77: .Pp
78: Both the manual section and description may be zero-length.
79: Entries are sequentially-numbered, but the filenames are unordered.
80: .Ss Keyword Database
81: The keyword database,
82: .Pa mandoc.db ,
83: is a
84: .Xr btree 3
85: database of nil-terminated keywords (record length is non-zero string
86: length plus one) mapping to a 8-byte binary field consisting of the
87: keyword type and source
88: .Sx Index Database
89: record number.
1.4 kristaps 90: The type, a 32-bit bit-mask in host order, consists of the following
91: fields:
1.1 kristaps 92: .Pp
93: .Bl -tag -width Ds -offset indent -compact
94: .It Li 0x01
95: The name of a manual page as given in the NAME section.
96: .It Li 0x02
97: A function prototype name as given in the SYNOPSIS section.
1.4 kristaps 98: .It Li 0x04
1.1 kristaps 99: A utility name as given in the SYNOPSIS section.
1.4 kristaps 100: .It Li 0x08
1.1 kristaps 101: An include file as given in the SYNOPSIS section.
1.4 kristaps 102: .It Li 0x10
1.1 kristaps 103: A variable name as given in the SYNOPSIS section.
1.4 kristaps 104: .It Li 0x20
1.1 kristaps 105: A standard as given in the STANDARDS section.
1.4 kristaps 106: .It Li 0x40
1.1 kristaps 107: An author as given in the AUTHORS section.
1.4 kristaps 108: .It Li 0x80
1.1 kristaps 109: A configuration as given in the SYNOPSIS section.
1.5 ! kristaps 110: .It Li 0x100
! 111: Free-form descriptive text as given in the NAME section.
1.1 kristaps 112: .El
113: .Pp
1.4 kristaps 114: The last four bytes are a host-ordered record number within the
1.1 kristaps 115: .Sx Index Database .
116: .Pp
117: The
118: .Nm
119: utility is
120: .Ud
121: .Sh FILES
122: .Bl -tag -width Ds
123: .It Pa mandoc.db
124: A
125: .Xr btree 3
126: keyword database mapping keywords to a type and file reference in
127: .Pa mandoc.index .
128: .It Pa mandoc.db~
129: Working copy of
130: .Pa mandoc.db .
131: .It Pa mandoc.index
132: A
133: .Xr recno 3
134: database of indexed file-names.
135: .It Pa mandoc.index~
136: Working copy of
137: .Pa mandoc.index .
138: .El
139: .Sh EXIT STATUS
140: .Ex -std
141: .Sh SEE ALSO
142: .Xr mandoc 1
143: .Sh AUTHORS
144: The
145: .Nm
146: utility was written by
147: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb