freebsd-dev/contrib/mdocml/mandoc.db.5

.\"	$Id: mandoc.db.5,v 1.2 2014/09/03 18:09:14 schwarze Exp $
.\"
.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: September 3 2014 $
.Dt MANDOC.DB 5
.Os
.Sh NAME
.Nm mandoc.db
.Nd manual page database
.Sh DESCRIPTION
The
.Nm
SQLite3 file format is used to store information about installed manual
pages to facilitate semantic searching for manuals.
Each manual page tree contains its own
.Nm
file; see
.Sx FILES
for examples.
.Pp
Such database files are generated by
.Xr makewhatis 8
and used by
.Xr apropos 1
and
.Xr whatis 1 .
.Pp
One line in the following tables describes:
.Bl -tag -width Ds
.It Sy mpages
One physical manual page file, no matter how many times and under which
names it may appear in the file system.
.It Sy mlinks
One entry in the file system, no matter which content it points to.
.It Sy names
One manual page name, no matter whether it appears in a page header,
in a NAME or SYNOPSIS section, or as a file name.
.It Sy keys
One chunk of text from some macro invocation.
.El
.Pp
Each record in the latter three tables uses its
.Va pageid
column to point to a record in the
.Sy mpages
table.
.Pp
The other columns are as follows; unless stated otherwise, they are
of type
.Vt TEXT .
.Bl -tag -width mpages.desc
.It Sy mpages.desc
The description line
.Pq Sq \&Nd
of the page.
.It Sy mpages.form
An
.Vt INTEGER
bit field.
If bit
.Dv FORM_GZ
is set, the page is compressed and requires
.Xr gunzip 1
for display.
If bit
.Dv FORM_SRC
is set, the page is unformatted, that is in
.Xr mdoc 7
or
.Xr man 7
format, and requires
.Xr mandoc 1
for display.
If bit
.Dv FORM_SRC
is not set, the page is formatted, i.e. a
.Sq cat
page.
.It Sy mlinks.sec
The manual section as found in the subdirectory name.
.It Sy mlinks.arch
The manual architecture as found in the subdirectory name, or
.Qq any .
.It Sy mlinks.name
The manual name as found in the file name.
.It Sy names.bits
An
.Vt INTEGER
bit mask telling whether the name came from a header line, from the
NAME or SYNOPSIS section, or from a file name.
Bits are defined in
.In mansearch.h .
.It Sy names.name
The name itself.
.It Sy keys.bits
An
.Vt INTEGER
bit mask telling which semantic contexts the key was found in;
defined in
.In mansearch.h ,
documented in
.Xr apropos 1 .
.It Sy keys.key
The string found in those contexts.
.El
.Sh FILES
.Bl -tag -width /usr/share/mandoc.db -compact
.It Pa /usr/share/mandoc.db
The manual page database for the base system.
.It Pa /usr/X11R6/mandoc.db
The same for the
.Xr X 7
Window System.
.It Pa /usr/local/mandoc.db
The same for
.Xr packages 7 .
.El
.Sh SEE ALSO
.Xr apropos 1 ,
.Xr man 1 ,
.Xr sqlite3 1 ,
.Xr whatis 1 ,
.Xr mansearch 3 ,
.Xr makewhatis 8
.Sh HISTORY
A manual page database
.Pa /usr/lib/whatis
first appeared in
.Bx 2 .
The present format first appeared in
.Ox 5.6 .
.Sh AUTHORS
.An -nosplit
The original version of
.Xr makewhatis 8
was written by
.An Bill Joy
in 1979.
An SQLite3 version was first implemented by
.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
in 2012.
The present database format was designed by
.An Ingo Schwarze Aq Mt schwarze@openbsd.org
in 2014.