From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from krisdoz.my.domain (kristaps@localhost [127.0.0.1]) by krisdoz.my.domain (8.14.3/8.14.3) with ESMTP id p34ArGSH006707 for ; Mon, 4 Apr 2011 06:53:16 -0400 (EDT) Received: (from kristaps@localhost) by krisdoz.my.domain (8.14.3/8.14.3/Submit) id p34ArFqv025657; Mon, 4 Apr 2011 06:53:15 -0400 (EDT) Date: Mon, 4 Apr 2011 06:53:15 -0400 (EDT) Message-Id: <201104041053.p34ArFqv025657@krisdoz.my.domain> X-Mailinglist: mdocml-source Reply-To: source@mdocml.bsd.lv MIME-Version: 1.0 From: kristaps@mdocml.bsd.lv To: source@mdocml.bsd.lv Subject: mdocml: Add manual page for mandoc-db (mostly to document the file X-Mailer: activitymail 1.26, http://search.cpan.org/dist/activitymail/ Content-Type: text/plain; charset=utf-8 Log Message: ----------- 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. Modified Files: -------------- mdocml: mandoc-db.c Added Files: ----------- mdocml: mandoc-db.1 Revision Data ------------- --- /dev/null +++ mandoc-db.1 @@ -0,0 +1,132 @@ +.\" $Id: mandoc-db.1,v 1.1 2011/04/04 10:53:15 kristaps Exp $ +.\" +.\" Copyright (c) 2011 Kristaps Dzonsons +.\" +.\" 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: April 4 2011 $ +.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. Index: mandoc-db.c =================================================================== RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/mandoc-db.c,v retrieving revision 1.3 retrieving revision 1.4 diff -Lmandoc-db.c -Lmandoc-db.c -u -p -r1.3 -r1.4 --- mandoc-db.c +++ mandoc-db.c @@ -61,7 +61,6 @@ static void dbt_append(DBT *, size_t 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); -- To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv