summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorKristaps Dzonsons <kristaps@bsd.lv>2011-04-04 10:53:15 +0000
committerKristaps Dzonsons <kristaps@bsd.lv>2011-04-04 10:53:15 +0000
commiteb26063e6d14c60d65335fb8795468d2abaca26a (patch)
tree25bcf38f670759b41fcab6dcd06e7d8fcde2659b
parentc07df5d52d6de4f2da056e0e2bdc6d7065f07835 (diff)
downloadmandoc-eb26063e6d14c60d65335fb8795468d2abaca26a.tar.gz
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.
-rw-r--r--mandoc-db.1132
-rw-r--r--mandoc-db.c33
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);