From: schwarze Date: Thu, 24 Apr 2014 19:08:01 +0000 (+0000) Subject: document the new makewhatis(8)/apropos(1) database format; X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=7f839e81bb4ed8c41c065ced2a0dc96e6d6103c7;p=openbsd 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 b7818444692..3d37fd20429 100644 --- 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 index 00000000000..ace24417eb7 --- /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 +.\" +.\" 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.