[BACK]Return to mandocdb.8 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mandocdb.8, Revision 1.3

1.3     ! kristaps    1: .\"    $Id: mandocdb.8,v 1.2 2011/07/15 10:15:24 kristaps Exp $
1.1       schwarze    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.3     ! kristaps   17: .Dd $Mdocdate: July 15 2011 $
1.1       schwarze   18: .Dt MANDOCDB 8
                     19: .Os
                     20: .Sh NAME
                     21: .Nm mandocdb
                     22: .Nd index UNIX manuals
                     23: .Sh SYNOPSIS
                     24: .Nm
1.3     ! kristaps   25: .Op Fl v
        !            26: .Op Ar dir...
        !            27: .Nm
        !            28: .Op Fl v
        !            29: .Fl d Ar dir
        !            30: .Op Ar
        !            31: .Nm
        !            32: .Op Fl v
        !            33: .Fl u Ar dir
        !            34: .Op Ar
1.1       schwarze   35: .Sh DESCRIPTION
                     36: The
                     37: .Nm
                     38: utility extracts keywords from
                     39: .Ux
1.3     ! kristaps   40: manuals and indexes them in a
        !            41: .Sx Keyword Database
        !            42: and
        !            43: .Sx Index Database
        !            44: for fast retrieval.
1.1       schwarze   45: The arguments are as follows:
                     46: .Bl -tag -width Ds
1.3     ! kristaps   47: .It Fl d Ar dir
        !            48: Remove
        !            49: .Ar
        !            50: from the databases in
        !            51: .Ar dir .
        !            52: .It Fl u Ar dir
        !            53: Update (remove and re-add)
        !            54: .Ar
        !            55: from the databases in
        !            56: .Ar dir .
1.2       kristaps   57: .It Ar dir...
1.3     ! kristaps   58: Recursively add files rooted at each
1.2       kristaps   59: .Ar dir
1.3     ! kristaps   60: to the databases in the respective
        !            61: .Ar dir .
1.2       kristaps   62: Existing databases are truncated.
1.3     ! kristaps   63: .It Fl v
        !            64: Verbose operation.
        !            65: Use once to display all files added or removed and twice for keywords as
        !            66: well.
1.1       schwarze   67: .El
                     68: .Pp
                     69: By default,
                     70: .Nm
1.3     ! kristaps   71: creates databases in each
        !            72: .Ar dir
        !            73: using files rooted in that directory.
1.1       schwarze   74: .Pp
1.2       kristaps   75: If fatal parse errors are encountered while parsing, the offending file
                     76: is printed to stderr, omitted from the index, and the parse continues
                     77: with the next input file.
1.1       schwarze   78: .Ss Index Database
                     79: The index database,
                     80: .Pa mandoc.index ,
                     81: is a
                     82: .Xr recno 3
                     83: database with record values consisting of
                     84: .Pp
                     85: .Bl -enum -compact
                     86: .It
                     87: a nil-terminated filename,
                     88: .It
                     89: a nil-terminated manual section,
                     90: .It
                     91: a nil-terminated manual title,
                     92: .It
                     93: a nil-terminated architecture
                     94: .Pq this is not often available
                     95: .It
                     96: and a nil-terminated description.
                     97: .El
                     98: .Pp
1.3     ! kristaps   99: Both the manual section and description may be zero-length if the record
        !           100: is unassigned.
1.1       schwarze  101: Entries are sequentially-numbered, but the filenames are unordered.
                    102: .Ss Keyword Database
                    103: The keyword database,
                    104: .Pa mandoc.db ,
                    105: is a
                    106: .Xr btree 3
                    107: database of nil-terminated keywords (record length is non-zero string
                    108: length plus one) mapping to a 8-byte binary field consisting of the
                    109: keyword type and source
                    110: .Sx Index Database
                    111: record number.
                    112: The type, a 32-bit bit-mask in host order, consists of the following
                    113: fields:
                    114: .Pp
                    115: .Bl -tag -width Ds -offset indent -compact
                    116: .It Li 0x01
                    117: The name of a manual page as given in the NAME section.
                    118: .It Li 0x02
                    119: A function prototype name as given in the SYNOPSIS section.
                    120: .It Li 0x04
                    121: A utility name as given in the SYNOPSIS section.
                    122: .It Li 0x08
                    123: An include file as given in the SYNOPSIS section.
                    124: .It Li 0x10
                    125: A variable name as given in the SYNOPSIS section.
                    126: .It Li 0x20
                    127: A standard as given in the STANDARDS section.
                    128: .It Li 0x40
                    129: An author as given in the AUTHORS section.
                    130: .It Li 0x80
                    131: A configuration as given in the SYNOPSIS section.
                    132: .It Li 0x100
                    133: Free-form descriptive text as given in the NAME section.
                    134: .It Li 0x200
                    135: Cross-links between manuals.
                    136: Listed as the link name, then a period, then the link section.
                    137: If the link has no section, the period terminates the string.
                    138: .It Li 0x400
                    139: Path reference as given in the FILES section.
                    140: .It Li 0x800
                    141: Environment variable as given in the ENVIRONMENT section.
                    142: .It Li 0x1000
                    143: Error codes as given in the ERRORS section.
                    144: .El
                    145: .Pp
                    146: The last four bytes are a host-ordered record number within the
                    147: .Sx Index Database .
                    148: .Pp
                    149: The
                    150: .Nm
                    151: utility is
                    152: .Ud
                    153: .Sh IMPLEMENTATION NOTES
                    154: The time to construct a new database pair grows linearly with the
1.3     ! kristaps  155: number of keywords in the input files.
1.1       schwarze  156: However, removing or updating entries with
1.3     ! kristaps  157: .Fl u
1.1       schwarze  158: or
1.3     ! kristaps  159: .Fl d ,
1.1       schwarze  160: respectively, grows as a multiple of the index length and input size.
                    161: .Sh FILES
                    162: .Bl -tag -width Ds
                    163: .It Pa mandoc.db
                    164: A
                    165: .Xr btree 3
                    166: keyword database mapping keywords to a type and file reference in
                    167: .Pa mandoc.index .
                    168: .It Pa mandoc.index
                    169: A
                    170: .Xr recno 3
                    171: database of indexed file-names.
                    172: .El
                    173: .Sh EXIT STATUS
                    174: The
                    175: .Nm
                    176: utility exits with one of the following values:
                    177: .Pp
                    178: .Bl -tag -width Ds -compact
                    179: .It 0
                    180: No errors occurred.
                    181: .It 5
                    182: Invalid command line arguments were specified.
                    183: No input files have been read.
                    184: .It 6
                    185: An operating system error occurred, for example memory exhaustion or an
                    186: error accessing input files.
                    187: Such errors cause
                    188: .Nm
                    189: to exit at once, possibly in the middle of parsing or formatting a file.
                    190: The output databases are corrupt and should be removed .
                    191: .El
                    192: .Sh SEE ALSO
1.3     ! kristaps  193: .Xr mandoc 1 ,
        !           194: .Xr btree 3 ,
        !           195: .Xr recno 3
1.1       schwarze  196: .Sh AUTHORS
                    197: The
                    198: .Nm
                    199: utility was written by
                    200: .An Kristaps Dzonsons Aq kristaps@bsd.lv .

CVSweb