mandocdb.8

   1 .\"     $Id: mandocdb.8,v 1.3 2011/07/15 17:59:29 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 15 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 v
  26 .Op Ar dir...
  27 .Nm
  28 .Op Fl v
  29 .Fl d Ar dir
  30 .Op Ar
  31 .Nm
  32 .Op Fl v
  33 .Fl u Ar dir
  34 .Op Ar
  35 .Sh DESCRIPTION
  36 The
  37 .Nm
  38 utility extracts keywords from
  39 .Ux
  40 manuals and indexes them in a
  41 .Sx Keyword Database
  42 and
  43 .Sx Index Database
  44 for fast retrieval.
  45 The arguments are as follows:
  46 .Bl -tag -width Ds
  47 .It Fl d Ar dir
  48 Remove
  49 .Ar
  50 from the databases in
  51 .Ar dir .
  52 .It Fl u Ar dir
  53 Update (remove and re-add)
  54 .Ar
  55 from the databases in
  56 .Ar dir .
  57 .It Ar dir...
  58 Recursively add files rooted at each
  59 .Ar dir
  60 to the databases in the respective
  61 .Ar dir .
  62 Existing databases are truncated.
  63 .It Fl v
  64 Verbose operation.
  65 Use once to display all files added or removed and twice for keywords as
  66 well.
  67 .El
  68 .Pp
  69 By default,
  70 .Nm
  71 creates databases in each
  72 .Ar dir
  73 using files rooted in that directory.
  74 .Pp
  75 If fatal parse errors are encountered while parsing, the offending file
  76 is printed to stderr, omitted from the index, and the parse continues
  77 with the next input file.
  78 .Ss Index Database
  79 The index database,
  80 .Pa mandoc.index ,
  81 is a
  82 .Xr recno 3
  83 database with record values consisting of
  84 .Pp
  85 .Bl -enum -compact
  86 .It
  87 a nil-terminated filename,
  88 .It
  89 a nil-terminated manual section,
  90 .It
  91 a nil-terminated manual title,
  92 .It
  93 a nil-terminated architecture
  94 .Pq this is not often available
  95 .It
  96 and a nil-terminated description.
  97 .El
  98 .Pp
  99 Both the manual section and description may be zero-length if the record
 100 is unassigned.
 101 Entries are sequentially-numbered, but the filenames are unordered.
 102 .Ss Keyword Database
 103 The keyword database,
 104 .Pa mandoc.db ,
 105 is a
 106 .Xr btree 3
 107 database of nil-terminated keywords (record length is non-zero string
 108 length plus one) mapping to a 8-byte binary field consisting of the
 109 keyword type and source
 110 .Sx Index Database
 111 record number.
 112 The type, a 32-bit bit-mask in host order, consists of the following
 113 fields:
 114 .Pp
 115 .Bl -tag -width Ds -offset indent -compact
 116 .It Li 0x01
 117 The name of a manual page as given in the NAME section.
 118 .It Li 0x02
 119 A function prototype name as given in the SYNOPSIS section.
 120 .It Li 0x04
 121 A utility name as given in the SYNOPSIS section.
 122 .It Li 0x08
 123 An include file as given in the SYNOPSIS section.
 124 .It Li 0x10
 125 A variable name as given in the SYNOPSIS section.
 126 .It Li 0x20
 127 A standard as given in the STANDARDS section.
 128 .It Li 0x40
 129 An author as given in the AUTHORS section.
 130 .It Li 0x80
 131 A configuration as given in the SYNOPSIS section.
 132 .It Li 0x100
 133 Free-form descriptive text as given in the NAME section.
 134 .It Li 0x200
 135 Cross-links between manuals.
 136 Listed as the link name, then a period, then the link section.
 137 If the link has no section, the period terminates the string.
 138 .It Li 0x400
 139 Path reference as given in the FILES section.
 140 .It Li 0x800
 141 Environment variable as given in the ENVIRONMENT section.
 142 .It Li 0x1000
 143 Error codes as given in the ERRORS section.
 144 .El
 145 .Pp
 146 The last four bytes are a host-ordered record number within the
 147 .Sx Index Database .
 148 .Pp
 149 The
 150 .Nm
 151 utility is
 152 .Ud
 153 .Sh IMPLEMENTATION NOTES
 154 The time to construct a new database pair grows linearly with the
 155 number of keywords in the input files.
 156 However, removing or updating entries with
 157 .Fl u
 158 or
 159 .Fl d ,
 160 respectively, grows as a multiple of the index length and input size.
 161 .Sh FILES
 162 .Bl -tag -width Ds
 163 .It Pa mandoc.db
 164 A
 165 .Xr btree 3
 166 keyword database mapping keywords to a type and file reference in
 167 .Pa mandoc.index .
 168 .It Pa mandoc.index
 169 A
 170 .Xr recno 3
 171 database of indexed file-names.
 172 .El
 173 .Sh EXIT STATUS
 174 The
 175 .Nm
 176 utility exits with one of the following values:
 177 .Pp
 178 .Bl -tag -width Ds -compact
 179 .It 0
 180 No errors occurred.
 181 .It 5
 182 Invalid command line arguments were specified.
 183 No input files have been read.
 184 .It 6
 185 An operating system error occurred, for example memory exhaustion or an
 186 error accessing input files.
 187 Such errors cause
 188 .Nm
 189 to exit at once, possibly in the middle of parsing or formatting a file.
 190 The output databases are corrupt and should be removed .
 191 .El
 192 .Sh SEE ALSO
 193 .Xr mandoc 1 ,
 194 .Xr btree 3 ,
 195 .Xr recno 3
 196 .Sh AUTHORS
 197 The
 198 .Nm
 199 utility was written by
 200 .An Kristaps Dzonsons Aq kristaps@bsd.lv .