external/bsd/mdocml/dist/mandocdb.8

   1 .\"     Id: mandocdb.8,v 1.20 2013/10/01 20:56:18 schwarze 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 October 1, 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 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 mandoc.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 mandoc.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 HISTORY
 140 A
 141 .Nm makewhatis
 142 utility first appeared in
 143 .Bx 2 .
 144 It was rewritten in
 145 .Xr perl 1
 146 for
 147 .Ox 2.7
 148 and in C for
 149 .Ox 5.1 .
 150 .Pp
 151 The
 152 .Ar dir
 153 argument first appeared in
 154 .Nx 1.0 ;
 155 the options
 156 .Fl dtu
 157 in
 158 .Ox 2.7 ;
 159 and the options
 160 .Fl aCvW
 161 in
 162 .Ox 5.1 .
 163 .Sh AUTHORS
 164 .An -nosplit
 165 .An Bill Joy
 166 wrote the original
 167 .Bx
 168 .Nm makewhatis
 169 in February 1979,
 170 .An Marc Espie
 171 started the Perl version in 2000,
 172 and the current version of
 173 .Nm
 174 was written by
 175 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 176 and
 177 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .