Annotation of mandoc/mandocdb.8, Revision 1.1
1.1 ! schwarze 1: .\" $Id: mandocdb.8,v 1.1 2011/07/14 10:57:02 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: 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
! 25: .Op Fl ruv
! 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.
! 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.
! 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.
! 58: .El
! 59: .Pp
! 60: By default,
! 61: .Nm
! 62: constructs a new
! 63: .Sx Index Database
! 64: and
! 65: .Sx Keyword Database
! 66: in the current working directory.
! 67: Existing databases are truncated.
! 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.
! 105: The type, a 32-bit bit-mask in host order, consists of the following
! 106: fields:
! 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.
! 113: .It Li 0x04
! 114: A utility name as given in the SYNOPSIS section.
! 115: .It Li 0x08
! 116: An include file as given in the SYNOPSIS section.
! 117: .It Li 0x10
! 118: A variable name as given in the SYNOPSIS section.
! 119: .It Li 0x20
! 120: A standard as given in the STANDARDS section.
! 121: .It Li 0x40
! 122: An author as given in the AUTHORS section.
! 123: .It Li 0x80
! 124: A configuration as given in the SYNOPSIS section.
! 125: .It Li 0x100
! 126: Free-form descriptive text as given in the NAME section.
! 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.
! 131: .It Li 0x400
! 132: Path reference as given in the FILES section.
! 133: .It Li 0x800
! 134: Environment variable as given in the ENVIRONMENT section.
! 135: .It Li 0x1000
! 136: Error codes as given in the ERRORS section.
! 137: .El
! 138: .Pp
! 139: The last four bytes are a host-ordered record number within the
! 140: .Sx Index Database .
! 141: .Pp
! 142: The
! 143: .Nm
! 144: utility is
! 145: .Ud
! 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.
! 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
! 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
! 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 mandocdb.8 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc