mandocdb.8

   1 .\"     $Id: mandocdb.8,v 1.21 2014/03/17 08:34:00 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\" Copyright (c) 2011, 2012 Ingo Schwarze <schwarze@openbsd.org>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd $Mdocdate: March 17 2014 $
  19 .Dt MANDOCDB 8
  20 .Os
  21 .Sh NAME
  22 .Nm mandocdb
  23 .Nd index UNIX manuals
  24 .Sh SYNOPSIS
  25 .Nm
  26 .Op Fl anvW
  27 .Op Fl C Ar file
  28 .Nm
  29 .Op Fl anvW
  30 .Ar dir ...
  31 .Nm
  32 .Op Fl nvW
  33 .Fl d Ar dir
  34 .Op Ar
  35 .Nm
  36 .Op Fl nvW
  37 .Fl u Ar dir
  38 .Op Ar
  39 .Nm
  40 .Fl t Ar
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 utility extracts keywords from
  45 .Ux
  46 manuals and indexes them in a database for fast retrieval by
  47 .Xr apropos 1 ,
  48 .Xr whatis 1 ,
  49 and
  50 .Xr man 1 Ns 's
  51 .Fl k
  52 option.
  53 .Pp
  54 By default,
  55 .Nm
  56 creates a database in each
  57 .Ar dir
  58 using the files
  59 .Sm off
  60 .Sy man Ar section Li /
  61 .Op Ar arch Li /
  62 .Ar title . section
  63 .Sm on
  64 and
  65 .Sm off
  66 .Sy cat Ar section Li /
  67 .Op Ar arch Li /
  68 .Ar title . Sy 0
  69 .Sm on
  70 in that directory.
  71 Existing databases are replaced.
  72 If
  73 .Ar dir
  74 is not provided,
  75 .Nm
  76 uses the default paths stipulated by
  77 .Xr manpath 1 ,
  78 or
  79 .Xr man.conf 5 .
  80 .Pp
  81 The arguments are as follows:
  82 .Bl -tag -width "-C file"
  83 .It Fl a
  84 Use all directories and files found below
  85 .Ar dir ... .
  86 .It Fl C Ar file
  87 Specify an alternative configuration
  88 .Ar file
  89 in
  90 .Xr man.conf 5
  91 format.
  92 .It Fl d Ar dir
  93 Merge (remove and re-add)
  94 .Ar
  95 to the database in
  96 .Ar dir .
  97 .It Fl n
  98 Do not create or modify any database;
  99 scan and parse only.
 100 .It Fl t Ar
 101 Check the given
 102 .Ar files
 103 for potential problems.
 104 Implies
 105 .Fl a ,
 106 .Fl n ,
 107 and
 108 .Fl W .
 109 All diagnostic messages are printed to the standard output;
 110 the standard error output is not used.
 111 .It Fl u Ar dir
 112 Remove
 113 .Ar
 114 from the database in
 115 .Ar dir .
 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 .Sh FILES
 127 .Bl -tag -width Ds
 128 .It Pa mandoc.db
 129 A database of manpages relative to the directory of the file.
 130 This file is portable across architectures and systems, so long as the
 131 manpage hierarchy it indexes does not change.
 132 .It Pa /etc/man.conf
 133 The default
 134 .Xr man 1
 135 configuration file.
 136 .El
 137 .Sh EXIT STATUS
 138 The
 139 .Nm
 140 utility exits with one of the following values:
 141 .Pp
 142 .Bl -tag -width Ds -compact
 143 .It 0
 144 No errors occurred.
 145 .It 5
 146 Invalid command line arguments were specified.
 147 No input files have been read.
 148 .It 6
 149 An operating system error occurred, for example memory exhaustion or an
 150 error accessing input files.
 151 Such errors cause
 152 .Nm
 153 to exit at once, possibly in the middle of parsing or formatting a file.
 154 The output databases are corrupt and should be removed.
 155 .El
 156 .Sh SEE ALSO
 157 .Xr apropos 1 ,
 158 .Xr man 1 ,
 159 .Xr whatis 1 ,
 160 .Xr man.conf 5
 161 .Sh HISTORY
 162 A
 163 .Nm makewhatis
 164 utility first appeared in
 165 .Bx 2 .
 166 It was rewritten in
 167 .Xr perl 1
 168 for
 169 .Ox 2.7
 170 and in C for
 171 .Ox 5.1 .
 172 .Pp
 173 The
 174 .Ar dir
 175 argument first appeared in
 176 .Nx 1.0 ;
 177 the options
 178 .Fl dtu
 179 in
 180 .Ox 2.7 ;
 181 and the options
 182 .Fl aCvW
 183 in
 184 .Ox 5.1 .
 185 .Sh AUTHORS
 186 .An -nosplit
 187 .An Bill Joy
 188 wrote the original
 189 .Bx
 190 .Nm makewhatis
 191 in February 1979,
 192 .An Marc Espie
 193 started the Perl version in 2000,
 194 and the current version of
 195 .Nm
 196 was written by
 197 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 198 and
 199 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .