Annotation of mandoc/makewhatis.1, Revision 1.13
1.13 ! kristaps 1: .\" $Id: makewhatis.1,v 1.12 2011/07/11 09:44:07 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.12 kristaps 17: .Dd $Mdocdate: July 11 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.13 ! kristaps 25: .Op Fl ruv
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.13 ! kristaps 45: .It Fl r
! 46: Remove entries.
! 47: This will remove the index and keyword references.
! 48: If the record is not found, it is ignored.
! 49: .It Fl u
! 50: Update the record.
! 51: This will first remove the record (as in
! 52: .Fl r )
! 53: then re-add it.
1.6 kristaps 54: .It Fl v
55: Verbose output.
56: If specified once, prints the name of each indexed file.
57: If twice, prints keywords for each file.
1.1 kristaps 58: .El
59: .Pp
60: By default,
61: .Nm
1.13 ! kristaps 62: constructs a new
1.1 kristaps 63: .Sx Index Database
64: and
65: .Sx Keyword Database
66: in the current working directory.
1.13 ! kristaps 67: Existing databases are truncated.
1.1 kristaps 68: .Pp
69: If fatal parse errors are encountered, the offending file is printed to
70: stderr, omitted from the index, and the parse continues with the next
71: input file.
72: .Ss Index Database
73: The index database,
74: .Pa mandoc.index ,
75: is a
76: .Xr recno 3
77: database with record values consisting of
78: .Pp
79: .Bl -enum -compact
80: .It
81: a nil-terminated filename,
82: .It
83: a nil-terminated manual section,
84: .It
85: a nil-terminated manual title,
86: .It
87: a nil-terminated architecture
88: .Pq this is not often available
89: .It
90: and a nil-terminated description.
91: .El
92: .Pp
93: Both the manual section and description may be zero-length.
94: Entries are sequentially-numbered, but the filenames are unordered.
95: .Ss Keyword Database
96: The keyword database,
97: .Pa mandoc.db ,
98: is a
99: .Xr btree 3
100: database of nil-terminated keywords (record length is non-zero string
101: length plus one) mapping to a 8-byte binary field consisting of the
102: keyword type and source
103: .Sx Index Database
104: record number.
1.4 kristaps 105: The type, a 32-bit bit-mask in host order, consists of the following
106: fields:
1.1 kristaps 107: .Pp
108: .Bl -tag -width Ds -offset indent -compact
109: .It Li 0x01
110: The name of a manual page as given in the NAME section.
111: .It Li 0x02
112: A function prototype name as given in the SYNOPSIS section.
1.4 kristaps 113: .It Li 0x04
1.1 kristaps 114: A utility name as given in the SYNOPSIS section.
1.4 kristaps 115: .It Li 0x08
1.1 kristaps 116: An include file as given in the SYNOPSIS section.
1.4 kristaps 117: .It Li 0x10
1.1 kristaps 118: A variable name as given in the SYNOPSIS section.
1.4 kristaps 119: .It Li 0x20
1.1 kristaps 120: A standard as given in the STANDARDS section.
1.4 kristaps 121: .It Li 0x40
1.1 kristaps 122: An author as given in the AUTHORS section.
1.4 kristaps 123: .It Li 0x80
1.1 kristaps 124: A configuration as given in the SYNOPSIS section.
1.5 kristaps 125: .It Li 0x100
126: Free-form descriptive text as given in the NAME section.
1.7 kristaps 127: .It Li 0x200
128: Cross-links between manuals.
129: Listed as the link name, then a period, then the link section.
130: If the link has no section, the period terminates the string.
1.8 kristaps 131: .It Li 0x400
132: Path reference as given in the FILES section.
1.9 kristaps 133: .It Li 0x800
134: Environment variable as given in the ENVIRONMENT section.
1.10 kristaps 135: .It Li 0x1000
136: Error codes as given in the ERRORS section.
1.1 kristaps 137: .El
138: .Pp
1.4 kristaps 139: The last four bytes are a host-ordered record number within the
1.1 kristaps 140: .Sx Index Database .
141: .Pp
142: The
143: .Nm
144: utility is
145: .Ud
1.13 ! kristaps 146: .Sh IMPLEMENTATION NOTES
! 147: The time to construct a new database pair grows linearly with the
! 148: number of keywords in the input.
! 149: However, removing or updating entries with
! 150: .Fl r
! 151: or
! 152: .Fl u ,
! 153: respectively, grows as a multiple of the index length and input size.
1.1 kristaps 154: .Sh FILES
155: .Bl -tag -width Ds
156: .It Pa mandoc.db
157: A
158: .Xr btree 3
159: keyword database mapping keywords to a type and file reference in
160: .Pa mandoc.index .
161: .It Pa mandoc.index
162: A
163: .Xr recno 3
164: database of indexed file-names.
165: .El
166: .Sh EXIT STATUS
1.12 kristaps 167: The
168: .Nm
169: utility exits with one of the following values:
170: .Pp
171: .Bl -tag -width Ds -compact
172: .It 0
173: No errors occurred.
174: .It 5
175: Invalid command line arguments were specified.
176: No input files have been read.
177: .It 6
178: An operating system error occurred, for example memory exhaustion or an
179: error accessing input files.
180: Such errors cause
181: .Nm
182: to exit at once, possibly in the middle of parsing or formatting a file.
183: The output databases are corrupt and should be removed .
184: .El
1.1 kristaps 185: .Sh SEE ALSO
186: .Xr mandoc 1
187: .Sh AUTHORS
188: The
189: .Nm
190: utility was written by
191: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to makewhatis.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc