Use size_t in manpath instead of int.

[mandoc.git] / mandocdb.8

diff --git a/mandocdb.8 b/mandocdb.8
index 38b928fda909af5317dc898af77bb0fa0c4e25b6..cb48359b340790a94e7fd60ef1713e372c8c74df 100644 (file)
--- a/mandocdb.8
+++ b/mandocdb.8
@@ -1,4 +1,4 @@
-.\"    $Id: mandocdb.8,v 1.14 2011/12/16 12:06:35 kristaps Exp $
+.\"    $Id: mandocdb.8,v 1.17 2011/12/25 21:00:23 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: December 16 2011 $
+.Dd $Mdocdate: December 25 2011 $

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


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

-.Op Fl av
+.Op Fl avW

 .Op Fl C Ar file
 .Nm
 .Op Fl C Ar file
 .Nm

-.Op Fl av
+.Op Fl avW

 .Ar dir ...
 .Nm
 .Ar dir ...
 .Nm

-.Op Fl v
+.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


@@ -44,7 +46,13 @@ manuals and indexes them in a
 .Sx Keyword Database
 and
 .Sx Index Database
 .Sx Keyword Database
 and
 .Sx Index Database

-for fast retrieval.
+for fast retrieval by
+.Xr apropos 1 ,
+.Xr whatis 1 ,
+and
+.Xr man 1 Ns 's
+.Fl k
+option.

 .Pp
 By default,
 .Nm
 .Pp
 By default,
 .Nm


@@ -88,6 +96,17 @@ Merge (remove and re-add)
 to the database in
 .Ar dir
 without truncating it.
 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


@@ -96,6 +115,9 @@ from the database in
 without truncating it.
 .It Fl v
 Display all files added or removed to the index.
 without truncating it.
 .It Fl v
 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,7 +125,7 @@ is printed to stderr, omitted from the index, and the parse continues
 with the next input file.
 .Ss Index Database
 The index database,
 with the next input file.
 .Ss Index Database
 The index database,

-.Pa mandoc.index ,
+.Pa whatis.index ,

 is a
 .Xr recno 3
 database with record values consisting of
 is a
 .Xr recno 3
 database with record values consisting of


@@ -139,14 +161,15 @@ Each of the above is NUL-terminated.
 If the record value is zero-length, it is unassigned.
 .Ss Keyword Database
 The keyword database,
 If the record value is zero-length, it is unassigned.
 .Ss Keyword Database
 The keyword database,

-.Pa mandoc.db ,
+.Pa whatis.db ,

 is a
 .Xr btree 3
 database of NUL-terminated keywords (record length is non-zero string
 is a
 .Xr btree 3
 database of NUL-terminated keywords (record length is non-zero string

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

 .Sx Index Database
 record number, both in network-byte order.
 .Sx Index Database
 record number, both in network-byte order.

+.Pp

 The type bit-mask consists of the following
 values mapping into
 .Xr mdoc 7
 The type bit-mask consists of the following
 values mapping into
 .Xr mdoc 7


@@ -192,9 +215,6 @@ macro identifiers:
 .It Li 0x0000001000000000ULL Ta \&Vt
 .It Li 0x0000002000000000ULL Ta \&Xr
 .El
 .It Li 0x0000001000000000ULL Ta \&Vt
 .It Li 0x0000002000000000ULL Ta \&Xr
 .El

-.Pp
-The last four bytes are a host-ordered record number within the
-.Sx Index Database .

 .Sh IMPLEMENTATION NOTES
 The time to construct a new database pair grows linearly with the
 number of keywords in the input files.
 .Sh IMPLEMENTATION NOTES
 The time to construct a new database pair grows linearly with the
 number of keywords in the input files.


@@ -205,12 +225,12 @@ or
 respectively, grows as a multiple of the index length and input size.
 .Sh FILES
 .Bl -tag -width Ds
 respectively, grows as a multiple of the index length and input size.
 .Sh FILES
 .Bl -tag -width Ds

-.It Pa mandoc.db
+.It Pa whatis.db

 A
 .Xr btree 3
 keyword database mapping keywords to a type and file reference in
 A
 .Xr btree 3
 keyword database mapping keywords to a type and file reference in

-.Pa mandoc.index .
-.It Pa mandoc.index
+.Pa whatis.index .
+.It Pa whatis.index

 A
 .Xr recno 3
 database of indexed file-names.
 A
 .Xr recno 3
 database of indexed file-names.


@@ -236,7 +256,7 @@ error accessing input files.
 Such errors cause
 .Nm
 to exit at once, possibly in the middle of parsing or formatting a file.
 Such errors cause
 .Nm
 to exit at once, possibly in the middle of parsing or formatting a file.

-The output databases are corrupt and should be removed .
+The output databases are corrupt and should be removed.

 .El
 .Sh DIAGNOSTICS
 If the following errors occur, the
 .El
 .Sh DIAGNOSTICS
 If the following errors occur, the