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