contrib/mdocml/mandocdb.8

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