===================================================================
RCS file: /cvs/mandoc/Attic/mandocdb.8,v
retrieving revision 1.2
retrieving revision 1.8
diff -u -p -r1.2 -r1.8
--- mandoc/Attic/mandocdb.8	2011/07/15 10:15:24	1.2
+++ mandoc/Attic/mandocdb.8	2011/11/28 01:37:34	1.8
@@ -1,4 +1,4 @@
-.\"	$Id: mandocdb.8,v 1.2 2011/07/15 10:15:24 kristaps Exp $
+.\"	$Id: mandocdb.8,v 1.8 2011/11/28 01:37:34 schwarze Exp $
 .\"
 .\" 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.
 .\"
-.Dd $Mdocdate: July 15 2011 $
+.Dd $Mdocdate: November 28 2011 $
 .Dt MANDOCDB 8
 .Os
 .Sh NAME
@@ -22,39 +22,75 @@
 .Nd index UNIX manuals
 .Sh SYNOPSIS
 .Nm
-.Ar dir...
+.Op Fl av
+.Op Ar dir ...
+.Nm
+.Op Fl v
+.Fl d Ar dir
+.Op Ar
+.Nm
+.Op Fl v
+.Fl u Ar dir
+.Op Ar
 .Sh DESCRIPTION
 The
 .Nm
 utility extracts keywords from
 .Ux
-manuals and indexes them for fast retrieval.
-The arguments are as follows:
-.Bl -tag -width Ds
-.It Ar dir...
-Recursively scan for
-.Xr mdoc 7
+manuals and indexes them in a
+.Sx Keyword Database
 and
-.Xr man 7
-.Ux
-manual files in each
-.Ar dir
-directory.
 .Sx Index Database
-and
-.Sx Keyword Database
-files are installed in each
-.Ar dir
-directory.
-Existing databases are truncated.
-.El
+for fast retrieval.
 .Pp
 By default,
 .Nm
-does nothing: the
-.Ar dir...
-invocation must be used.
+creates databases in each
+.Ar dir
+using the files
+.Sm off
+.Sy man Ar section Li /
+.Op Ar arch Li /
+.Ar title . section
+.Sm on
+and
+.Sm off
+.Sy cat Ar section Li /
+.Op Ar arch Li /
+.Ar title . Sy 0
+.Sm on
+in that directory;
+existing databases are truncated.
+If
+.Ar dir
+is not provided,
+.Nm
+uses the default paths stipulated by
+.Xr man 1 .
 .Pp
+The arguments are as follows:
+.Bl -tag -width Ds
+.It Fl a
+Use all directories and files found below
+.Ar dir ... .
+.It Fl d Ar dir
+Merge (remove and re-add)
+.Ar
+to the database in
+.Ar dir
+without truncating it.
+.It Fl u Ar dir
+Remove
+.Ar
+from the database in
+.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.
+.El
+.Pp
 If fatal parse errors are encountered while parsing, the offending file
 is printed to stderr, omitted from the index, and the parse continues
 with the next input file.
@@ -67,26 +103,36 @@ database with record values consisting of
 .Pp
 .Bl -enum -compact
 .It
-a nil-terminated filename,
+the string
+.Cm mdoc ,
+.Cm man ,
+or
+.Cm cat
+to indicate the file type,
 .It
-a nil-terminated manual section,
+the filename,
 .It
-a nil-terminated manual title,
+the manual section,
 .It
-a nil-terminated architecture
-.Pq this is not often available
+the manual title,
 .It
-and a nil-terminated description.
+the architecture
+.Pq often empty ,
+.It
+and the description.
 .El
 .Pp
-Both the manual section and description may be zero-length.
+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.
 .Ss Keyword Database
 The keyword database,
 .Pa mandoc.db ,
 is a
 .Xr btree 3
-database of nil-terminated keywords (record length is non-zero string
+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
 .Sx Index Database
@@ -134,11 +180,11 @@ utility is
 .Ud
 .Sh IMPLEMENTATION NOTES
 The time to construct a new database pair grows linearly with the
-number of keywords in the input.
+number of keywords in the input files.
 However, removing or updating entries with
-.Fl r
+.Fl u
 or
-.Fl u ,
+.Fl d ,
 respectively, grows as a multiple of the index length and input size.
 .Sh FILES
 .Bl -tag -width Ds
@@ -172,9 +218,13 @@ to exit at once, possibly in the middle of parsing or 
 The output databases are corrupt and should be removed .
 .El
 .Sh SEE ALSO
-.Xr mandoc 1
+.Xr man 1 ,
+.Xr mandoc 1 ,
+.Xr btree 3 ,
+.Xr recno 3
 .Sh AUTHORS
 The
 .Nm
 utility was written by
-.An Kristaps Dzonsons Aq kristaps@bsd.lv .
+.An Kristaps Dzonsons ,
+.Mt kristaps@bsd.lv .