makewhatis.1

   1 .\"     $Id: makewhatis.1,v 1.10 2011/07/01 13:46:39 kristaps 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: July 1 2011 $
  18 .Dt MAKEWHATIS 1
  19 .Os
  20 .Sh NAME
  21 .Nm makewhatis
  22 .Nd index UNIX manuals
  23 .Sh SYNOPSIS
  24 .Nm
  25 .Op Fl v
  26 .Op Fl d Ar dir
  27 .Ar
  28 .Sh DESCRIPTION
  29 The
  30 .Nm
  31 utility extracts keywords from
  32 .Ux
  33 manuals and indexes them for fast retrieval.
  34 The arguments are as follows:
  35 .Bl -tag -width Ds
  36 .It Fl d Ar dir
  37 The directory into which to write the keyword and index databases.
  38 .It Ar
  39 Read input from zero or more files in
  40 .Xr mdoc 7
  41 or
  42 .Xr man 7
  43 .Ux
  44 manual format.
  45 .It Fl v
  46 Verbose output.
  47 If specified once, prints the name of each indexed file.
  48 If twice, prints keywords for each file.
  49 .El
  50 .Pp
  51 By default,
  52 .Nm
  53 constructs the
  54 .Sx Index Database
  55 and
  56 .Sx Keyword Database
  57 in the current working directory.
  58 .Pp
  59 If fatal parse errors are encountered, the offending file is printed to
  60 stderr, omitted from the index, and the parse continues with the next
  61 input file.
  62 .Ss Index Database
  63 The index database,
  64 .Pa mandoc.index ,
  65 is a
  66 .Xr recno 3
  67 database with record values consisting of
  68 .Pp
  69 .Bl -enum -compact
  70 .It
  71 a nil-terminated filename,
  72 .It
  73 a nil-terminated manual section,
  74 .It
  75 a nil-terminated manual title,
  76 .It
  77 a nil-terminated architecture
  78 .Pq this is not often available
  79 .It
  80 and a nil-terminated description.
  81 .El
  82 .Pp
  83 Both the manual section and description may be zero-length.
  84 Entries are sequentially-numbered, but the filenames are unordered.
  85 .Ss Keyword Database
  86 The keyword database,
  87 .Pa mandoc.db ,
  88 is a
  89 .Xr btree 3
  90 database of nil-terminated keywords (record length is non-zero string
  91 length plus one) mapping to a 8-byte binary field consisting of the
  92 keyword type and source
  93 .Sx Index Database
  94 record number.
  95 The type, a 32-bit bit-mask in host order, consists of the following
  96 fields:
  97 .Pp
  98 .Bl -tag -width Ds -offset indent -compact
  99 .It Li 0x01
 100 The name of a manual page as given in the NAME section.
 101 .It Li 0x02
 102 A function prototype name as given in the SYNOPSIS section.
 103 .It Li 0x04
 104 A utility name as given in the SYNOPSIS section.
 105 .It Li 0x08
 106 An include file as given in the SYNOPSIS section.
 107 .It Li 0x10
 108 A variable name as given in the SYNOPSIS section.
 109 .It Li 0x20
 110 A standard as given in the STANDARDS section.
 111 .It Li 0x40
 112 An author as given in the AUTHORS section.
 113 .It Li 0x80
 114 A configuration as given in the SYNOPSIS section.
 115 .It Li 0x100
 116 Free-form descriptive text as given in the NAME section.
 117 .It Li 0x200
 118 Cross-links between manuals.
 119 Listed as the link name, then a period, then the link section.
 120 If the link has no section, the period terminates the string.
 121 .It Li 0x400
 122 Path reference as given in the FILES section.
 123 .It Li 0x800
 124 Environment variable as given in the ENVIRONMENT section.
 125 .It Li 0x1000
 126 Error codes as given in the ERRORS section.
 127 .El
 128 .Pp
 129 The last four bytes are a host-ordered record number within the
 130 .Sx Index Database .
 131 .Pp
 132 The
 133 .Nm
 134 utility is
 135 .Ud
 136 .Sh FILES
 137 .Bl -tag -width Ds
 138 .It Pa mandoc.db
 139 A
 140 .Xr btree 3
 141 keyword database mapping keywords to a type and file reference in
 142 .Pa mandoc.index .
 143 .It Pa mandoc.db~
 144 Working copy of
 145 .Pa mandoc.db .
 146 .It Pa mandoc.index
 147 A
 148 .Xr recno 3
 149 database of indexed file-names.
 150 .It Pa mandoc.index~
 151 Working copy of
 152 .Pa mandoc.index .
 153 .El
 154 .Sh EXIT STATUS
 155 .Ex -std
 156 .Sh SEE ALSO
 157 .Xr mandoc 1
 158 .Sh AUTHORS
 159 The
 160 .Nm
 161 utility was written by
 162 .An Kristaps Dzonsons Aq kristaps@bsd.lv .