Annotation of mandoc/makewhatis.1, Revision 1.1
1.1 ! kristaps 1: .\" $Id: mandoc-db.1,v 1.5 2011/05/04 20:43:38 kristaps Exp $
! 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: May 4 2011 $
! 18: .Dt MANDOC-DB 1
! 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.
! 90: The type, an unsigned 32-bit integer in host order, is one of the
! 91: following:
! 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.
! 98: .It Li 0x03
! 99: A utility name as given in the SYNOPSIS section.
! 100: .It Li 0x04
! 101: An include file as given in the SYNOPSIS section.
! 102: .It Li 0x05
! 103: A variable name as given in the SYNOPSIS section.
! 104: .It Li 0x06
! 105: A standard as given in the STANDARDS section.
! 106: .It Li 0x07
! 107: An author as given in the AUTHORS section.
! 108: .It Li 0x08
! 109: A configuration as given in the SYNOPSIS section.
! 110: .El
! 111: .Pp
! 112: If a value is encountered outside of this range, the database is
! 113: corrupt.
! 114: .Pp
! 115: The latter four bytes are a host-ordered record number within the
! 116: .Sx Index Database .
! 117: .Pp
! 118: The
! 119: .Nm
! 120: utility is
! 121: .Ud
! 122: .Sh FILES
! 123: .Bl -tag -width Ds
! 124: .It Pa mandoc.db
! 125: A
! 126: .Xr btree 3
! 127: keyword database mapping keywords to a type and file reference in
! 128: .Pa mandoc.index .
! 129: .It Pa mandoc.db~
! 130: Working copy of
! 131: .Pa mandoc.db .
! 132: .It Pa mandoc.index
! 133: A
! 134: .Xr recno 3
! 135: database of indexed file-names.
! 136: .It Pa mandoc.index~
! 137: Working copy of
! 138: .Pa mandoc.index .
! 139: .El
! 140: .Sh EXIT STATUS
! 141: .Ex -std
! 142: .Sh SEE ALSO
! 143: .Xr mandoc 1
! 144: .Sh AUTHORS
! 145: The
! 146: .Nm
! 147: utility was written by
! 148: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
! 149: .Sh CAVEATS
! 150: Only
! 151: .Xr mdoc 7
! 152: manuals are processed.
CVSweb