Add manual page for mandoc-db (mostly to document the file format of

the generated index and keyword databases).  Add some documentation
within mandoc-db.c.

2 files changed, 149 insertions, 16 deletions

diff --git a/mandoc-db.1 b/mandoc-db.1
new file mode 100644
index 00000000..3aee3b69
--- /dev/null
+++ b/mandoc-db.1
@@ -0,0 +1,132 @@
+.\"	$Id$
+.\"
+.\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
+.\"
+.\" 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$
+.Dt MANDOC-DB 1
+.Os
+.Sh NAME
+.Nm mandoc-db
+.Nd index UNIX manuals
+.Sh SYNOPSIS
+.Nm
+.Op Fl d Ar dir
+.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 Fl d Ar dir
+The directory into which to write the keyword and index databases.
+.It Ar
+Read input from zero or more files in
+.Xr mdoc 7
+or
+.Xr man 7
+.Ux
+manual format.
+.El
+.Pp
+By default,
+.Nm
+constructs the
+.Sx Index Database
+and
+.Sx Keyword Database
+in the current working directory.
+.Pp
+If fatal parse errors are encountered, the offending file is printed to
+stderr, omitted from the index, and the parse continues with the next
+input file.
+.Ss Index Database
+The index database,
+.Pa mandoc.index ,
+is a
+.Xr recno 3
+database of nil-terminated filenames (record length is non-zero string
+length plus one) passed to
+.Nm .
+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
+length plus one) mapping to a 8-byte binary field consisting of the
+keyword type and source
+.Sx Index Database
+record number.
+The type, an unsigned 32-bit integer in host order, is one of the
+following:
+.Pp
+.Bl -tag -width Ds -offset indent -compact
+.It Li 0x01
+The name of a manual page as given in the NAME section.
+.It Li 0x02
+A function prototype name as given in the SYNOPSIS section.
+.It Li 0x03
+A utility name as given in the SYNOPSIS section.
+.It Li 0x04
+An include file as given in the SYNOPSIS section.
+.It Li 0x05
+A variable name as given in the SYNOPSIS section.
+.El
+.Pp
+If a value is encountered outside of this range, the database is
+corrupt.
+.Pp
+The latter four bytes are a host-ordered record number within the
+.Sx Index Database .
+.Pp
+The
+.Nm
+utility is
+.Ud
+.Sh FILES
+.Bl -tag -width Ds
+.It Pa mandoc.db
+A
+.Xr btree 3
+keyword database mapping keywords to a type and file reference in
+.Pa mandoc.index .
+.It Pa mandoc.db~
+Working copy of
+.Pa mandoc.db .
+.It Pa mandoc.index
+A
+.Xr recno 3
+database of indexed file-names.
+.It Pa mandoc.index~
+Working copy of
+.Pa mandoc.index .
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh SEE ALSO
+.Xr mandoc 1
+.Sh AUTHORS
+The
+.Nm
+utility was written by
+.An Kristaps Dzonsons Aq kristaps@bsd.lv .
+.Sh CAVEATS
+Only
+.Xr mdoc 7
+manuals are processed.
diff --git a/mandoc-db.c b/mandoc-db.c
index acc7bff9..1a3db9e8 100644
--- a/mandoc-db.c
+++ b/mandoc-db.c
@@ -61,7 +61,6 @@ static	void		  dbt_append(DBT *, size_t *, const char *);
 static	void		  dbt_appendb(DBT *, size_t *, 
 				const void *, size_t);
 static	void		  dbt_init(DBT *, size_t *);
-static	void		  version(void);
 static	void		  usage(void);
 static	void		  pmdoc(DB *, const char *, 
 				DBT *, size_t *, DBT *, 
@@ -234,14 +233,11 @@ main(int argc, char *argv[])
 
 	dir = "";
 
-	while (-1 != (c = getopt(argc, argv, "d:V")))
+	while (-1 != (c = getopt(argc, argv, "d:")))
 		switch (c) {
 		case ('d'):
 			dir = optarg;
 			break;
-		case ('V'):
-			version();
-			return((int)MANDOCLEVEL_OK);
 		default:
 			usage();
 			return((int)MANDOCLEVEL_BADARG);
@@ -329,8 +325,10 @@ main(int argc, char *argv[])
 	while (NULL != (fn = *argv++)) {
 		mparse_reset(mp);
 
-		if (mparse_readfd(mp, -1, fn) >= MANDOCLEVEL_FATAL)
+		if (mparse_readfd(mp, -1, fn) >= MANDOCLEVEL_FATAL) {
+			fprintf(stderr, "%s: Parse failure\n", fn);
 			continue;
+		}
 
 		mparse_result(mp, &mdoc, NULL);
 		if (NULL == mdoc)
@@ -443,11 +441,22 @@ pmdoc_Fd(MDOC_ARGS)
 		return;
 	if (NULL == (n = n->child) || MDOC_TEXT != n->type)
 		return;
+
+	/*
+	 * Only consider those `Fd' macro fields that begin with an
+	 * "inclusion" token (versus, e.g., #define).
+	 */
 	if (strcmp("#include", n->string))
 		return;
+
 	if (NULL == (n = n->next) || MDOC_TEXT != n->type)
 		return;
 
+	/*
+	 * Strip away the enclosing angle brackets and make sure we're
+	 * not zero-length.
+	 */
+
 	start = n->string;
 	if ('<' == *start)
 		start++;
@@ -501,7 +510,7 @@ pmdoc_Fn(MDOC_ARGS)
 	if (NULL == cp)
 		cp = n->child->string;
 
-	/* Ignore pointers. */
+	/* Strip away pointer symbol. */
 
 	while ('*' == *cp)
 		cp++;
@@ -528,7 +537,7 @@ pmdoc_Vt(MDOC_ARGS)
 		return;
 
 	/*
-	 * Strip away leading '*' and trailing ';'.
+	 * Strip away leading pointer symbol '*' and trailing ';'.
 	 */
 
 	start = n->last->string;
@@ -650,18 +659,10 @@ pmdoc(DB *db, const char *dbn,
 }
 
 static void
-version(void)
-{
-
-	printf("%s %s\n", progname, VERSION);
-}
-
-static void
 usage(void)
 {
 
 	fprintf(stderr, "usage: %s "
-			"[-V] "
 			"[-d path] "
 			"[file...]\n", 
 			progname);