mandocdb.8

   1 .\"     $Id: mandocdb.8,v 1.18 2012/06/08 10:43:01 kristaps Exp $
   2 .\"
   3 .\" Copyright (c) 2011, 2012 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: June 8 2012 $
  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 anvW
  26 .Op Fl C Ar file
  27 .Nm
  28 .Op Fl anvW
  29 .Ar dir ...
  30 .Nm
  31 .Op Fl nvW
  32 .Fl d Ar dir
  33 .Op Ar
  34 .Nm
  35 .Op Fl nvW
  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 database for fast retrieval by
  46 .Xr apropos 1 ,
  47 .Xr whatis 1 ,
  48 and
  49 .Xr man 1 .
  50 .Pp
  51 By default,
  52 .Nm
  53 creates a database 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 replaced.
  69 If
  70 .Ar dir
  71 is not provided,
  72 .Nm
  73 uses the default paths stipulated by
  74 .Xr manpath 1 ,
  75 or
  76 .Xr man.conf 5 .
  77 .Pp
  78 The arguments are as follows:
  79 .Bl -tag -width "-C file"
  80 .It Fl a
  81 Use all directories and files found below
  82 .Ar dir ... .
  83 .It Fl C Ar file
  84 Specify an alternative configuration
  85 .Ar file
  86 in
  87 .Xr man.conf 5
  88 format.
  89 .It Fl d Ar dir
  90 Merge (remove and re-add)
  91 .Ar
  92 to the database in
  93 .Ar dir .
  94 .It Fl n
  95 Do not create or modify any database;
  96 scan and parse only.
  97 .It Fl t Ar
  98 Check the given
  99 .Ar files
 100 for potential problems.
 101 Implies
 102 .Fl a ,
 103 .Fl n ,
 104 and
 105 .Fl W .
 106 All diagnostic messages are printed to the standard output;
 107 the standard error output is not used.
 108 .It Fl u Ar dir
 109 Remove
 110 .Ar
 111 from the database in
 112 .Ar dir .
 113 .It Fl v
 114 Display all files added or removed to the index.
 115 .It Fl W
 116 Print warnings about potential problems with manual pages
 117 to the standard error output.
 118 .El
 119 .Pp
 120 If fatal parse errors are encountered while parsing, the offending file
 121 is printed to stderr, omitted from the index, and the parse continues
 122 with the next input file.
 123 .Sh FILES
 124 .Bl -tag -width Ds
 125 .It Pa mandocdb.db
 126 A database of manpages relative to the directory of the file.
 127 This file is portable across architectures and systems, so long as the
 128 manpage hierarchy it indexes does not change.
 129 .It Pa mandocdb.db~
 130 A temporary database used during scanning and parsing.
 131 .El
 132 .Sh EXIT STATUS
 133 .Ex -std
 134 .Sh SEE ALSO
 135 .Xr apropos 1 ,
 136 .Xr man 1 ,
 137 .Xr whatis 1 ,
 138 .Xr man.conf 5
 139 .Sh AUTHORS
 140 The
 141 .Nm
 142 utility was written by
 143 .An Kristaps Dzonsons ,
 144 .Mt kristaps@bsd.lv ,
 145 and
 146 .An Ingo Schwarze ,
 147 .Mt schwarze@openbsd.org .