version 1.2, 2011/07/15 10:15:24 |
version 1.8, 2011/11/28 01:37:34 |
|
|
.Nd index UNIX manuals |
.Nd index UNIX manuals |
.Sh SYNOPSIS |
.Sh SYNOPSIS |
.Nm |
.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 |
.Sh DESCRIPTION |
The |
The |
.Nm |
.Nm |
utility extracts keywords from |
utility extracts keywords from |
.Ux |
.Ux |
manuals and indexes them for fast retrieval. |
manuals and indexes them in a |
The arguments are as follows: |
.Sx Keyword Database |
.Bl -tag -width Ds |
|
.It Ar dir... |
|
Recursively scan for |
|
.Xr mdoc 7 |
|
and |
and |
.Xr man 7 |
|
.Ux |
|
manual files in each |
|
.Ar dir |
|
directory. |
|
.Sx Index Database |
.Sx Index Database |
and |
for fast retrieval. |
.Sx Keyword Database |
|
files are installed in each |
|
.Ar dir |
|
directory. |
|
Existing databases are truncated. |
|
.El |
|
.Pp |
.Pp |
By default, |
By default, |
.Nm |
.Nm |
does nothing: the |
creates databases in each |
.Ar dir... |
.Ar dir |
invocation must be used. |
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 |
.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 |
If fatal parse errors are encountered while parsing, the offending file |
is printed to stderr, omitted from the index, and the parse continues |
is printed to stderr, omitted from the index, and the parse continues |
with the next input file. |
with the next input file. |
Line 67 database with record values consisting of |
|
Line 103 database with record values consisting of |
|
.Pp |
.Pp |
.Bl -enum -compact |
.Bl -enum -compact |
.It |
.It |
a nil-terminated filename, |
the string |
|
.Cm mdoc , |
|
.Cm man , |
|
or |
|
.Cm cat |
|
to indicate the file type, |
.It |
.It |
a nil-terminated manual section, |
the filename, |
.It |
.It |
a nil-terminated manual title, |
the manual section, |
.It |
.It |
a nil-terminated architecture |
the manual title, |
.Pq this is not often available |
|
.It |
.It |
and a nil-terminated description. |
the architecture |
|
.Pq often empty , |
|
.It |
|
and the description. |
.El |
.El |
.Pp |
.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. |
Entries are sequentially-numbered, but the filenames are unordered. |
.Ss Keyword Database |
.Ss Keyword Database |
The keyword database, |
The keyword database, |
.Pa mandoc.db , |
.Pa mandoc.db , |
is a |
is a |
.Xr btree 3 |
.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 |
length plus one) mapping to a 8-byte binary field consisting of the |
keyword type and source |
keyword type and source |
.Sx Index Database |
.Sx Index Database |
|
|
.Ud |
.Ud |
.Sh IMPLEMENTATION NOTES |
.Sh IMPLEMENTATION NOTES |
The time to construct a new database pair grows linearly with the |
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 |
However, removing or updating entries with |
.Fl r |
.Fl u |
or |
or |
.Fl u , |
.Fl d , |
respectively, grows as a multiple of the index length and input size. |
respectively, grows as a multiple of the index length and input size. |
.Sh FILES |
.Sh FILES |
.Bl -tag -width Ds |
.Bl -tag -width Ds |
Line 172 to exit at once, possibly in the middle of parsing or |
|
Line 218 to exit at once, possibly in the middle of parsing or |
|
The output databases are corrupt and should be removed . |
The output databases are corrupt and should be removed . |
.El |
.El |
.Sh SEE ALSO |
.Sh SEE ALSO |
.Xr mandoc 1 |
.Xr man 1 , |
|
.Xr mandoc 1 , |
|
.Xr btree 3 , |
|
.Xr recno 3 |
.Sh AUTHORS |
.Sh AUTHORS |
The |
The |
.Nm |
.Nm |
utility was written by |
utility was written by |
.An Kristaps Dzonsons Aq kristaps@bsd.lv . |
.An Kristaps Dzonsons , |
|
.Mt kristaps@bsd.lv . |