contrib/mdocml/mandoc.db.5

   1 .\"     $Id: mandoc.db.5,v 1.3 2014/12/30 21:34:57 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: December 30 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 An
  71 .Vt INTEGER
  72 bit field.
  73 If bit
  74 .Dv FORM_GZ
  75 is set, the page is compressed and requires
  76 .Xr gunzip 1
  77 for display.
  78 If bit
  79 .Dv FORM_SRC
  80 is set, the page is unformatted, that is in
  81 .Xr mdoc 7
  82 or
  83 .Xr man 7
  84 format, and requires
  85 .Xr mandoc 1
  86 for display.
  87 If bit
  88 .Dv FORM_SRC
  89 is not set, the page is formatted, i.e. a
  90 .Sq cat
  91 page.
  92 .It Sy mlinks.sec
  93 The manual section as found in the subdirectory name.
  94 .It Sy mlinks.arch
  95 The manual architecture as found in the subdirectory name, or
  96 .Qq any .
  97 .It Sy mlinks.name
  98 The manual name as found in the file name.
  99 .It Sy names.bits
 100 An
 101 .Vt INTEGER
 102 bit mask telling whether the name came from a header line, from the
 103 NAME or SYNOPSIS section, or from a file name.
 104 Bits are defined in
 105 .In mansearch.h .
 106 .It Sy names.name
 107 The name itself.
 108 .It Sy keys.bits
 109 An
 110 .Vt INTEGER
 111 bit mask telling which semantic contexts the key was found in;
 112 defined in
 113 .In mansearch.h ,
 114 documented in
 115 .Xr apropos 1 .
 116 .It Sy keys.key
 117 The string found in those contexts.
 118 .El
 119 .Sh FILES
 120 .Bl -tag -width /usr/share/man/mandoc.db -compact
 121 .It Pa /usr/share/man/mandoc.db
 122 The manual page database for the base system.
 123 .It Pa /usr/X11R6/man/mandoc.db
 124 The same for the
 125 .Xr X 7
 126 Window System.
 127 .It Pa /usr/local/man/mandoc.db
 128 The same for
 129 .Xr packages 7 .
 130 .El
 131 .Sh SEE ALSO
 132 .Xr apropos 1 ,
 133 .Xr man 1 ,
 134 .Xr sqlite3 1 ,
 135 .Xr whatis 1 ,
 136 .Xr mansearch 3 ,
 137 .Xr makewhatis 8
 138 .Sh HISTORY
 139 A manual page database
 140 .Pa /usr/lib/whatis
 141 first appeared in
 142 .Bx 2 .
 143 The present format first appeared in
 144 .Ox 5.6 .
 145 .Sh AUTHORS
 146 .An -nosplit
 147 The original version of
 148 .Xr makewhatis 8
 149 was written by
 150 .An Bill Joy
 151 in 1979.
 152 An SQLite3 version was first implemented by
 153 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
 154 in 2012.
 155 The present database format was designed by
 156 .An Ingo Schwarze Aq Mt schwarze@openbsd.org
 157 in 2014.