Implement test mode (makewhatis -t), required for pkg_create(8).

[mandoc.git] / mandocdb.8

diff --git a/mandocdb.8 b/mandocdb.8
index 48ae0d0ac4707265c4f6b0ffd7b92e3ad30764bd..270bab92fa0c02f7932103d7ea0407264b9406ec 100644 (file)
--- a/mandocdb.8
+++ b/mandocdb.8
@@ -1,4 +1,4 @@
-.\"    $Id: mandocdb.8,v 1.9 2011/11/29 11:17:47 kristaps Exp $
+.\"    $Id: mandocdb.8,v 1.15 2011/12/25 13:08:12 schwarze Exp $

 .\"
 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\"
 .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"


@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: November 29 2011 $
+.Dd $Mdocdate: December 25 2011 $

 .Dt MANDOCDB 8
 .Os
 .Sh NAME
 .Dt MANDOCDB 8
 .Os
 .Sh NAME


@@ -22,16 +22,21 @@
 .Nd index UNIX manuals
 .Sh SYNOPSIS
 .Nm
 .Nd index UNIX manuals
 .Sh SYNOPSIS
 .Nm

-.Op Fl av
-.Op Ar dir ...
+.Op Fl avW
+.Op Fl C Ar file

 .Nm
 .Nm

-.Op Fl v
+.Op Fl avW
+.Ar dir ...
+.Nm
+.Op Fl vW

 .Fl d Ar dir
 .Op Ar
 .Nm
 .Fl d Ar dir
 .Op Ar
 .Nm

-.Op Fl v
+.Op Fl vW

 .Fl u Ar dir
 .Op Ar
 .Fl u Ar dir
 .Op Ar

+.Nm
+.Fl t Ar

 .Sh DESCRIPTION
 The
 .Nm
 .Sh DESCRIPTION
 The
 .Nm


@@ -69,16 +74,33 @@ uses the default paths stipulated by
 .Xr man 1 .
 .Pp
 The arguments are as follows:
 .Xr man 1 .
 .Pp
 The arguments are as follows:

-.Bl -tag -width Ds
+.Bl -tag -width "-C file"

 .It Fl a
 Use all directories and files found below
 .Ar dir ... .
 .It Fl a
 Use all directories and files found below
 .Ar dir ... .

+.It Fl C Ar file
+Specify an alternative configuration
+.Ar file
+in
+.Xr man.conf 5
+format.

 .It Fl d Ar dir
 Merge (remove and re-add)
 .Ar
 to the database in
 .Ar dir
 without truncating it.
 .It Fl d Ar dir
 Merge (remove and re-add)
 .Ar
 to the database in
 .Ar dir
 without truncating it.

+.It Fl t Ar
+Check the given
+.Ar files
+for potential problems.
+No databases are modified.
+Implies
+.Fl a
+and
+.Fl W .
+All diagnostic messages are printed to the standard output;
+the standard error output is not used.

 .It Fl u Ar dir
 Remove
 .Ar
 .It Fl u Ar dir
 Remove
 .Ar


@@ -86,9 +108,10 @@ from the database in
 .Ar dir
 without truncating it.
 .It Fl v
 .Ar dir
 without truncating it.
 .It Fl v

-Verbose operation.
-Use once to display all files added or removed and twice for keywords as
-well.
+Display all files added or removed to the index.
+.It Fl W
+Print warnings about potential problems with manual pages
+to the standard error output.

 .El
 .Pp
 If fatal parse errors are encountered while parsing, the offending file
 .El
 .Pp
 If fatal parse errors are encountered while parsing, the offending file


@@ -103,20 +126,19 @@ database with record values consisting of
 .Pp
 .Bl -enum -compact
 .It
 .Pp
 .Bl -enum -compact
 .It

-the string
-.Cm mdoc ,
-.Cm man ,
+the character
+.Cm d ,
+.Cm a ,

 or
 or

-.Cm cat
+.Cm c

 to indicate the file type
 .Po
 to indicate the file type
 .Po

-file in

 .Xr mdoc 7 ,
 .Xr man 7 ,
 and post-formatted, respectively
 .Pc ,
 .It
 .Xr mdoc 7 ,
 .Xr man 7 ,
 and post-formatted, respectively
 .Pc ,
 .It

-the filename,
+the filename relative to the databases' path,

 .It
 the manual section,
 .It
 .It
 the manual section,
 .It


@@ -130,20 +152,18 @@ and the description.
 .Pp
 Each of the above is NUL-terminated.
 .Pp
 .Pp
 Each of the above is NUL-terminated.
 .Pp

-Both the manual section and description may be zero-length if the record
-is unassigned.
-Entries are sequentially-numbered, but the filenames are unordered.
+If the record value is zero-length, it is unassigned.

 .Ss Keyword Database
 The keyword database,
 .Pa mandoc.db ,
 is a
 .Xr btree 3
 database of NUL-terminated keywords (record length is non-zero string
 .Ss Keyword Database
 The keyword database,
 .Pa mandoc.db ,
 is a
 .Xr btree 3
 database of NUL-terminated keywords (record length is non-zero string

-length plus one) mapping to a 8-byte binary field consisting of the
-keyword type and source
+length plus one) mapping to a 12-byte binary field consisting of the
+64-bit keyword type and 32-bit source

 .Sx Index Database
 .Sx Index Database

-record number.
-The type, a 64-bit bit-mask in host order, consists of the following
+record number, both in network-byte order.
+The type bit-mask consists of the following

 values mapping into
 .Xr mdoc 7
 macro identifiers:
 values mapping into
 .Xr mdoc 7
 macro identifiers:


@@ -210,6 +230,10 @@ keyword database mapping keywords to a type and file reference in
 A
 .Xr recno 3
 database of indexed file-names.
 A
 .Xr recno 3
 database of indexed file-names.

+.It Pa /etc/man.conf
+The default
+.Xr man 1
+configuration file.

 .El
 .Sh EXIT STATUS
 The
 .El
 .Sh EXIT STATUS
 The


@@ -230,10 +254,33 @@ Such errors cause
 to exit at once, possibly in the middle of parsing or formatting a file.
 The output databases are corrupt and should be removed .
 .El
 to exit at once, possibly in the middle of parsing or formatting a file.
 The output databases are corrupt and should be removed .
 .El

+.Sh DIAGNOSTICS
+If the following errors occur, the
+.Nm
+databases should be rebuilt.
+.Bl -diag
+.It "%s: Corrupt database"
+The keyword database file indicated by
+.Pa %s
+is unreadable.
+.It "%s: Corrupt index"
+The index database file indicated by
+.Pa %s
+is unreadable.
+.It "%s: Path too long"
+The file
+.Pa %s
+is too long.
+This usually indicates database corruption or invalid command-line
+arguments.
+.El

 .Sh SEE ALSO
 .Sh SEE ALSO

+.Xr apropos 1 ,

 .Xr man 1 ,
 .Xr man 1 ,

+.Xr whatis 1 ,

 .Xr btree 3 ,
 .Xr btree 3 ,

-.Xr recno 3
+.Xr recno 3 ,
+.Xr man.conf 5

 .Sh AUTHORS
 The
 .Nm
 .Sh AUTHORS
 The
 .Nm