contrib/mdocml/mandoc.db.5

   1 .\"     $Id: mandoc.db.5,v 1.1 2014/04/15 20:18:26 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
   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: April 15 2014 $
  18 .Dt MANDOC.DB 5
  19 .Os
  20 .Sh NAME
  21 .Nm mandoc.db
  22 .Nd manual page database
  23 .Sh DESCRIPTION
  24 The
  25 .Nm
  26 SQLite3 file format is used to store information about installed manual
  27 pages to facilitate semantic searching for manuals.
  28 Each manual page tree contains its own
  29 .Nm
  30 file; see
  31 .Sx FILES
  32 for examples.
  33 .Pp
  34 Such database files are generated by
  35 .Xr makewhatis 8
  36 and used by
  37 .Xr apropos 1
  38 and
  39 .Xr whatis 1 .
  40 .Pp
  41 One line in the following tables describes:
  42 .Bl -tag -width Ds
  43 .It Sy mpages
  44 One physical manual page file, no matter how many times and under which
  45 names it may appear in the file system.
  46 .It Sy mlinks
  47 One entry in the file system, no matter which content it points to.
  48 .It Sy names
  49 One manual page name, no matter whether it appears in a page header,
  50 in a NAME or SYNOPSIS section, or as a file name.
  51 .It Sy keys
  52 One chunk of text from some macro invocation.
  53 .El
  54 .Pp
  55 Each record in the latter three tables uses its
  56 .Va pageid
  57 column to point to a record in the
  58 .Sy mpages
  59 table.
  60 .Pp
  61 The other columns are as follows; unless stated otherwise, they are
  62 of type
  63 .Vt TEXT .
  64 .Bl -tag -width mpages.desc
  65 .It Sy mpages.desc
  66 The description line
  67 .Pq Sq \&Nd
  68 of the page.
  69 .It Sy mpages.form
  70 The
  71 .Vt INTEGER
  72 1 if the page is unformatted, i.e. in
  73 .Xr mdoc 7
  74 or
  75 .Xr man 7
  76 format, and 2 if it is formatted, i.e. a
  77 .Sq cat
  78 page.
  79 .It Sy mlinks.sec
  80 The manual section as found in the subdirectory name.
  81 .It Sy mlinks.arch
  82 The manual architecture as found in the subdirectory name, or
  83 .Qq any .
  84 .It Sy mlinks.name
  85 The manual name as found in the file name.
  86 .It Sy names.bits
  87 An
  88 .Vt INTEGER
  89 bit mask telling whether the name came from a header line, from the
  90 NAME or SYNOPSIS section, or from a file name.
  91 Bits are defined in
  92 .In mansearch.h .
  93 .It Sy names.name
  94 The name itself.
  95 .It Sy keys.bits
  96 An
  97 .Vt INTEGER
  98 bit mask telling which semantic contexts the key was found in;
  99 defined in
 100 .In mansearch.h ,
 101 documented in
 102 .Xr apropos 1 .
 103 .It Sy keys.key
 104 The string found in those contexts.
 105 .El
 106 .Sh FILES
 107 .Bl -tag -width /usr/share/mandoc.db -compact
 108 .It Pa /usr/share/mandoc.db
 109 The manual page database for the base system.
 110 .It Pa /usr/X11R6/mandoc.db
 111 The same for the
 112 .Xr X 7
 113 Window System.
 114 .It Pa /usr/local/mandoc.db
 115 The same for
 116 .Xr packages 7 .
 117 .El
 118 .Sh SEE ALSO
 119 .Xr apropos 1 ,
 120 .Xr man 1 ,
 121 .Xr sqlite3 1 ,
 122 .Xr whatis 1 ,
 123 .Xr mansearch 3 ,
 124 .Xr makewhatis 8
 125 .Sh HISTORY
 126 A manual page database
 127 .Pa /usr/lib/whatis
 128 first appeared in
 129 .Bx 2 .
 130 The present format first appeared in
 131 .Ox 5.6 .
 132 .Sh AUTHORS
 133 .An -nosplit
 134 The original version of
 135 .Xr makewhatis 8
 136 was written by
 137 .An Bill Joy
 138 in 1979.
 139 An SQLite3 version was first implemented by
 140 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 141 in 2012.
 142 The present database format was designed by
 143 .An Ingo Schwarze Aq Mt schwarze@openbsd.org
 144 in 2014.