Return to mandoc-db.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mandoc-db.1, Revision 1.4

1.4     ! kristaps    1: .\"    $Id: mandoc-db.1,v 1.3 2011/04/28 10:44:02 kristaps Exp $
1.1       kristaps    2: .\"
                      3: .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv>
                      4: .\"
                      5: .\" Permission to use, copy, modify, and distribute this software for any
                      6: .\" purpose with or without fee is hereby granted, provided that the above
                      7: .\" copyright notice and this permission notice appear in all copies.
                      8: .\"
                      9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
                     10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
                     11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
                     12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
                     14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
                     15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
                     16: .\"
1.4     ! kristaps   17: .Dd $Mdocdate: April 28 2011 $
1.1       kristaps   18: .Dt MANDOC-DB 1
                     19: .Os
                     20: .Sh NAME
                     21: .Nm mandoc-db
                     22: .Nd index UNIX manuals
                     23: .Sh SYNOPSIS
                     24: .Nm
                     25: .Op Fl d Ar dir
                     26: .Ar
                     27: .Sh DESCRIPTION
                     28: The
                     29: .Nm
                     30: utility extracts keywords from
                     31: .Ux
                     32: manuals and indexes them for fast retrieval.
                     33: The arguments are as follows:
                     34: .Bl -tag -width Ds
                     35: .It Fl d Ar dir
                     36: The directory into which to write the keyword and index databases.
                     37: .It Ar
                     38: Read input from zero or more files in
                     39: .Xr mdoc 7
                     40: or
                     41: .Xr man 7
                     42: .Ux
                     43: manual format.
                     44: .El
                     45: .Pp
                     46: By default,
                     47: .Nm
                     48: constructs the
                     49: .Sx Index Database
                     50: and
                     51: .Sx Keyword Database
                     52: in the current working directory.
                     53: .Pp
                     54: If fatal parse errors are encountered, the offending file is printed to
                     55: stderr, omitted from the index, and the parse continues with the next
                     56: input file.
                     57: .Ss Index Database
                     58: The index database,
                     59: .Pa mandoc.index ,
                     60: is a
                     61: .Xr recno 3
1.2       kristaps   62: database with record values consisting of
                     63: .Pp
                     64: .Bl -enum -compact
                     65: .It
                     66: a nil-terminated filename,
                     67: .It
                     68: a nil-terminated manual section,
                     69: .It
1.4     ! kristaps   70: a nil-terminated manual title,
        !            71: .It
1.2       kristaps   72: and a nil-terminated description.
                     73: .El
                     74: .Pp
                     75: Both the manual section and description may be zero-length.
1.1       kristaps   76: Entries are sequentially-numbered, but the filenames are unordered.
                     77: .Ss Keyword Database
                     78: The keyword database,
                     79: .Pa mandoc.db ,
                     80: is a
                     81: .Xr btree 3
                     82: database of nil-terminated keywords (record length is non-zero string
                     83: length plus one) mapping to a 8-byte binary field consisting of the
                     84: keyword type and source
                     85: .Sx Index Database
                     86: record number.
                     87: The type, an unsigned 32-bit integer in host order, is one of the
                     88: following:
                     89: .Pp
                     90: .Bl -tag -width Ds -offset indent -compact
                     91: .It Li 0x01
                     92: The name of a manual page as given in the NAME section.
                     93: .It Li 0x02
                     94: A function prototype name as given in the SYNOPSIS section.
                     95: .It Li 0x03
                     96: A utility name as given in the SYNOPSIS section.
                     97: .It Li 0x04
                     98: An include file as given in the SYNOPSIS section.
                     99: .It Li 0x05
                    100: A variable name as given in the SYNOPSIS section.
1.3       kristaps  101: .It Li 0x06
                    102: A standard as given in the STANDARDS section.
1.4     ! kristaps  103: .It Li 0x07
        !           104: An author as given in the AUTHORS section.
1.1       kristaps  105: .El
                    106: .Pp
                    107: If a value is encountered outside of this range, the database is
                    108: corrupt.
                    109: .Pp
                    110: The latter four bytes are a host-ordered record number within the
                    111: .Sx Index Database .
                    112: .Pp
                    113: The
                    114: .Nm
                    115: utility is
                    116: .Ud
                    117: .Sh FILES
                    118: .Bl -tag -width Ds
                    119: .It Pa mandoc.db
                    120: A
                    121: .Xr btree 3
                    122: keyword database mapping keywords to a type and file reference in
                    123: .Pa mandoc.index .
                    124: .It Pa mandoc.db~
                    125: Working copy of
                    126: .Pa mandoc.db .
                    127: .It Pa mandoc.index
                    128: A
                    129: .Xr recno 3
                    130: database of indexed file-names.
                    131: .It Pa mandoc.index~
                    132: Working copy of
                    133: .Pa mandoc.index .
                    134: .El
                    135: .Sh EXIT STATUS
                    136: .Ex -std
                    137: .Sh SEE ALSO
                    138: .Xr mandoc 1
                    139: .Sh AUTHORS
                    140: The
                    141: .Nm
                    142: utility was written by
                    143: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
                    144: .Sh CAVEATS
                    145: Only
                    146: .Xr mdoc 7
                    147: manuals are processed.