document the new makewhatis(8)/apropos(1) database format;

original idea to have some documentation about this by espie@;
ok jmc@

diff --git a/share/man/man5/Makefile b/share/man/man5/Makefile
index b781844..3d37fd2 100644 (file)
--- a/share/man/man5/Makefile
+++ b/share/man/man5/Makefile
@@ -1,11 +1,11 @@
-#      $OpenBSD: Makefile,v 1.50 2014/04/19 18:39:51 tedu Exp $
+#      $OpenBSD: Makefile,v 1.51 2014/04/24 19:08:01 schwarze Exp $
 #      $NetBSD: Makefile,v 1.14 1995/05/11 23:13:15 cgd Exp $
 
 MAN=   acct.5 ar.5 bsd.port.mk.5 bsd.port.arch.mk.5 bsd.regress.mk.5 \
        changelist.5 core.5 \
        defaultdomain.5 dir.5 disktab.5 elf.5 ethers.5 fbtab.5 files.conf.5 \
        fs.5 fstab.5 genassym.cf.5 group.5 hostname.if.5 \
-       hosts.5 intro.5 login.conf.5 mixerctl.conf.5 \
+       hosts.5 intro.5 login.conf.5 mandoc.db.5 mixerctl.conf.5 \
        mk.conf.5 moduli.5 motd.5 myname.5 netgroup.5 networks.5 passwd.5 \
        pf.conf.5 pf.os.5 port-modules.5 printcap.5 protocols.5 \
        ranlib.5 remote.5 resolv.conf.5 rpc.5 ruby-module.5 \

diff --git a/share/man/man5/mandoc.db.5 b/share/man/man5/mandoc.db.5
new file mode 100644 (file)
index 0000000..ace2441
--- /dev/null
+++ b/share/man/man5/mandoc.db.5
@@ -0,0 +1,143 @@
+.\"    $OpenBSD: mandoc.db.5,v 1.1 2014/04/24 19:08:01 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: April 24 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
+The
+.Vt INTEGER
+1 if the page is unformatted, i.e. in
+.Xr mdoc 7
+or
+.Xr man 7
+format, and 2 if it 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 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.