mandocdb.8

   1 .\"     $Id: mandocdb.8,v 1.10 2011/12/01 21:05:49 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: December 1 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 av
  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 .Pp
  46 By default,
  47 .Nm
  48 creates databases in each
  49 .Ar dir
  50 using the files
  51 .Sm off
  52 .Sy man Ar section Li /
  53 .Op Ar arch Li /
  54 .Ar title . section
  55 .Sm on
  56 and
  57 .Sm off
  58 .Sy cat Ar section Li /
  59 .Op Ar arch Li /
  60 .Ar title . Sy 0
  61 .Sm on
  62 in that directory;
  63 existing databases are truncated.
  64 If
  65 .Ar dir
  66 is not provided,
  67 .Nm
  68 uses the default paths stipulated by
  69 .Xr man 1 .
  70 .Pp
  71 The arguments are as follows:
  72 .Bl -tag -width Ds
  73 .It Fl a
  74 Use all directories and files found below
  75 .Ar dir ... .
  76 .It Fl d Ar dir
  77 Merge (remove and re-add)
  78 .Ar
  79 to the database in
  80 .Ar dir
  81 without truncating it.
  82 .It Fl u Ar dir
  83 Remove
  84 .Ar
  85 from the database in
  86 .Ar dir
  87 without truncating it.
  88 .It Fl v
  89 Display all files added or removed to the index.
  90 .El
  91 .Pp
  92 If fatal parse errors are encountered while parsing, the offending file
  93 is printed to stderr, omitted from the index, and the parse continues
  94 with the next input file.
  95 .Ss Index Database
  96 The index database,
  97 .Pa mandoc.index ,
  98 is a
  99 .Xr recno 3
 100 database with record values consisting of
 101 .Pp
 102 .Bl -enum -compact
 103 .It
 104 the string
 105 .Cm mdoc ,
 106 .Cm man ,
 107 or
 108 .Cm cat
 109 to indicate the file type
 110 .Po
 111 file in
 112 .Xr mdoc 7 ,
 113 .Xr man 7 ,
 114 and post-formatted, respectively
 115 .Pc ,
 116 .It
 117 the filename,
 118 .It
 119 the manual section,
 120 .It
 121 the manual title,
 122 .It
 123 the architecture
 124 .Pq often empty ,
 125 .It
 126 and the description.
 127 .El
 128 .Pp
 129 Each of the above is NUL-terminated.
 130 .Pp
 131 Both the manual section and description may be zero-length if the record
 132 is unassigned.
 133 Entries are sequentially-numbered, but the filenames are unordered.
 134 .Ss Keyword Database
 135 The keyword database,
 136 .Pa mandoc.db ,
 137 is a
 138 .Xr btree 3
 139 database of NUL-terminated keywords (record length is non-zero string
 140 length plus one) mapping to a 8-byte binary field consisting of the
 141 keyword type and source
 142 .Sx Index Database
 143 record number.
 144 The type, a 64-bit bit-mask in host order, consists of the following
 145 values mapping into
 146 .Xr mdoc 7
 147 macro identifiers:
 148 .Pp
 149 .Bl -column "x0x0000000000000001ULLx" "xLix" -offset indent -compact
 150 .It Li 0x0000000000000001ULL Ta \&An
 151 .It Li 0x0000000000000002ULL Ta \&Ar
 152 .It Li 0x0000000000000004ULL Ta \&At
 153 .It Li 0x0000000000000008ULL Ta \&Bsx
 154 .It Li 0x0000000000000010ULL Ta \&Bx
 155 .It Li 0x0000000000000020ULL Ta \&Cd
 156 .It Li 0x0000000000000040ULL Ta \&Cm
 157 .It Li 0x0000000000000080ULL Ta \&Dv
 158 .It Li 0x0000000000000100ULL Ta \&Dx
 159 .It Li 0x0000000000000200ULL Ta \&Em
 160 .It Li 0x0000000000000400ULL Ta \&Er
 161 .It Li 0x0000000000000800ULL Ta \&Ev
 162 .It Li 0x0000000000001000ULL Ta \&Fa
 163 .It Li 0x0000000000002000ULL Ta \&Fl
 164 .It Li 0x0000000000004000ULL Ta \&Fn
 165 .It Li 0x0000000000008000ULL Ta \&Ft
 166 .It Li 0x0000000000010000ULL Ta \&Fx
 167 .It Li 0x0000000000020000ULL Ta \&Ic
 168 .It Li 0x0000000000040000ULL Ta \&In
 169 .It Li 0x0000000000080000ULL Ta \&Lb
 170 .It Li 0x0000000000100000ULL Ta \&Li
 171 .It Li 0x0000000000200000ULL Ta \&Lk
 172 .It Li 0x0000000000400000ULL Ta \&Ms
 173 .It Li 0x0000000000800000ULL Ta \&Mt
 174 .It Li 0x0000000001000000ULL Ta \&Nd
 175 .It Li 0x0000000002000000ULL Ta \&Nm
 176 .It Li 0x0000000004000000ULL Ta \&Nx
 177 .It Li 0x0000000008000000ULL Ta \&Ox
 178 .It Li 0x0000000010000000ULL Ta \&Pa
 179 .It Li 0x0000000020000000ULL Ta \&Rs
 180 .It Li 0x0000000040000000ULL Ta \&Sh
 181 .It Li 0x0000000080000000ULL Ta \&Ss
 182 .It Li 0x0000000100000000ULL Ta \&St
 183 .It Li 0x0000000200000000ULL Ta \&Sy
 184 .It Li 0x0000000400000000ULL Ta \&Tn
 185 .It Li 0x0000000800000000ULL Ta \&Va
 186 .It Li 0x0000001000000000ULL Ta \&Vt
 187 .It Li 0x0000002000000000ULL Ta \&Xr
 188 .El
 189 .Pp
 190 The last four bytes are a host-ordered record number within the
 191 .Sx Index Database .
 192 .Sh IMPLEMENTATION NOTES
 193 The time to construct a new database pair grows linearly with the
 194 number of keywords in the input files.
 195 However, removing or updating entries with
 196 .Fl u
 197 or
 198 .Fl d ,
 199 respectively, grows as a multiple of the index length and input size.
 200 .Sh FILES
 201 .Bl -tag -width Ds
 202 .It Pa mandoc.db
 203 A
 204 .Xr btree 3
 205 keyword database mapping keywords to a type and file reference in
 206 .Pa mandoc.index .
 207 .It Pa mandoc.index
 208 A
 209 .Xr recno 3
 210 database of indexed file-names.
 211 .El
 212 .Sh EXIT STATUS
 213 The
 214 .Nm
 215 utility exits with one of the following values:
 216 .Pp
 217 .Bl -tag -width Ds -compact
 218 .It 0
 219 No errors occurred.
 220 .It 5
 221 Invalid command line arguments were specified.
 222 No input files have been read.
 223 .It 6
 224 An operating system error occurred, for example memory exhaustion or an
 225 error accessing input files.
 226 Such errors cause
 227 .Nm
 228 to exit at once, possibly in the middle of parsing or formatting a file.
 229 The output databases are corrupt and should be removed .
 230 .El
 231 .Sh DIAGNOSTICS
 232 If the following errors occur, the
 233 .Nm
 234 databases should be rebuilt.
 235 .Bl -diag
 236 .It "%s: Corrupt database"
 237 The keyword database file indicated by
 238 .Pa %s
 239 is unreadable.
 240 .It "%s: Corrupt index"
 241 The index database file indicated by
 242 .Pa %s
 243 is unreadable.
 244 .It "%s: Path too long"
 245 The file
 246 .Pa %s
 247 is too long.
 248 This usually indicates database corruption or invalid command-line
 249 arguments.
 250 .El
 251 .Sh SEE ALSO
 252 .Xr man 1 ,
 253 .Xr btree 3 ,
 254 .Xr recno 3
 255 .Sh AUTHORS
 256 The
 257 .Nm
 258 utility was written by
 259 .An Kristaps Dzonsons ,
 260 .Mt kristaps@bsd.lv .