mandocdb.8

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