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

Annotation of mandoc/mandocdb.8, Revision 1.11

1.11    ! kristaps    1: .\"    $Id: mandocdb.8,v 1.10 2011/12/01 21:05:49 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.11    ! kristaps   17: .Dd $Mdocdate: December 1 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.7       schwarze   25: .Op Fl av
1.8       schwarze   26: .Op Ar dir ...
1.3       kristaps   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.7       schwarze   45: .Pp
1.8       schwarze   46: By default,
                     47: .Nm
                     48: creates databases in each
                     49: .Ar dir
                     50: using the files
                     51: .Sm off
                     52: .Sy man Ar section Li /
                     53: .Op Ar arch Li /
                     54: .Ar title . section
                     55: .Sm on
                     56: and
                     57: .Sm off
                     58: .Sy cat Ar section Li /
                     59: .Op Ar arch Li /
                     60: .Ar title . Sy 0
                     61: .Sm on
                     62: in that directory;
                     63: existing databases are truncated.
                     64: If
                     65: .Ar dir
                     66: is not provided,
                     67: .Nm
                     68: uses the default paths stipulated by
                     69: .Xr man 1 .
                     70: .Pp
1.1       schwarze   71: The arguments are as follows:
                     72: .Bl -tag -width Ds
1.7       schwarze   73: .It Fl a
                     74: Use all directories and files found below
                     75: .Ar dir ... .
1.3       kristaps   76: .It Fl d Ar dir
1.5       kristaps   77: Merge (remove and re-add)
1.3       kristaps   78: .Ar
1.8       schwarze   79: to the database in
                     80: .Ar dir
                     81: without truncating it.
1.3       kristaps   82: .It Fl u Ar dir
1.5       kristaps   83: Remove
1.3       kristaps   84: .Ar
1.8       schwarze   85: from the database in
1.2       kristaps   86: .Ar dir
1.8       schwarze   87: without truncating it.
1.3       kristaps   88: .It Fl v
1.10      kristaps   89: Display all files added or removed to the index.
1.1       schwarze   90: .El
                     91: .Pp
1.2       kristaps   92: If fatal parse errors are encountered while parsing, the offending file
                     93: is printed to stderr, omitted from the index, and the parse continues
                     94: with the next input file.
1.1       schwarze   95: .Ss Index Database
                     96: The index database,
                     97: .Pa mandoc.index ,
                     98: is a
                     99: .Xr recno 3
                    100: database with record values consisting of
                    101: .Pp
                    102: .Bl -enum -compact
                    103: .It
1.8       schwarze  104: the string
                    105: .Cm mdoc ,
                    106: .Cm man ,
                    107: or
                    108: .Cm cat
1.9       kristaps  109: to indicate the file type
                    110: .Po
                    111: file in
                    112: .Xr mdoc 7 ,
                    113: .Xr man 7 ,
                    114: and post-formatted, respectively
                    115: .Pc ,
1.1       schwarze  116: .It
1.8       schwarze  117: the filename,
1.1       schwarze  118: .It
1.8       schwarze  119: the manual section,
1.1       schwarze  120: .It
1.8       schwarze  121: the manual title,
1.1       schwarze  122: .It
1.8       schwarze  123: the architecture
                    124: .Pq often empty ,
                    125: .It
                    126: and the description.
1.1       schwarze  127: .El
                    128: .Pp
1.8       schwarze  129: Each of the above is NUL-terminated.
                    130: .Pp
1.3       kristaps  131: Both the manual section and description may be zero-length if the record
                    132: is unassigned.
1.1       schwarze  133: Entries are sequentially-numbered, but the filenames are unordered.
                    134: .Ss Keyword Database
                    135: The keyword database,
                    136: .Pa mandoc.db ,
                    137: is a
                    138: .Xr btree 3
1.8       schwarze  139: database of NUL-terminated keywords (record length is non-zero string
1.11    ! kristaps  140: length plus one) mapping to a 12-byte binary field consisting of the
        !           141: 64-bit keyword type and 32-bit source
1.1       schwarze  142: .Sx Index Database
1.11    ! kristaps  143: record number, both in network-byte order.
        !           144: The typet bit-mask consists of the following
1.9       kristaps  145: values mapping into
                    146: .Xr mdoc 7
                    147: macro identifiers:
                    148: .Pp
                    149: .Bl -column "x0x0000000000000001ULLx" "xLix" -offset indent -compact
                    150: .It Li 0x0000000000000001ULL Ta \&An
                    151: .It Li 0x0000000000000002ULL Ta \&Ar
                    152: .It Li 0x0000000000000004ULL Ta \&At
                    153: .It Li 0x0000000000000008ULL Ta \&Bsx
                    154: .It Li 0x0000000000000010ULL Ta \&Bx
                    155: .It Li 0x0000000000000020ULL Ta \&Cd
                    156: .It Li 0x0000000000000040ULL Ta \&Cm
                    157: .It Li 0x0000000000000080ULL Ta \&Dv
                    158: .It Li 0x0000000000000100ULL Ta \&Dx
                    159: .It Li 0x0000000000000200ULL Ta \&Em
                    160: .It Li 0x0000000000000400ULL Ta \&Er
                    161: .It Li 0x0000000000000800ULL Ta \&Ev
                    162: .It Li 0x0000000000001000ULL Ta \&Fa
                    163: .It Li 0x0000000000002000ULL Ta \&Fl
                    164: .It Li 0x0000000000004000ULL Ta \&Fn
                    165: .It Li 0x0000000000008000ULL Ta \&Ft
                    166: .It Li 0x0000000000010000ULL Ta \&Fx
                    167: .It Li 0x0000000000020000ULL Ta \&Ic
                    168: .It Li 0x0000000000040000ULL Ta \&In
                    169: .It Li 0x0000000000080000ULL Ta \&Lb
                    170: .It Li 0x0000000000100000ULL Ta \&Li
                    171: .It Li 0x0000000000200000ULL Ta \&Lk
                    172: .It Li 0x0000000000400000ULL Ta \&Ms
                    173: .It Li 0x0000000000800000ULL Ta \&Mt
                    174: .It Li 0x0000000001000000ULL Ta \&Nd
                    175: .It Li 0x0000000002000000ULL Ta \&Nm
                    176: .It Li 0x0000000004000000ULL Ta \&Nx
                    177: .It Li 0x0000000008000000ULL Ta \&Ox
                    178: .It Li 0x0000000010000000ULL Ta \&Pa
                    179: .It Li 0x0000000020000000ULL Ta \&Rs
                    180: .It Li 0x0000000040000000ULL Ta \&Sh
                    181: .It Li 0x0000000080000000ULL Ta \&Ss
                    182: .It Li 0x0000000100000000ULL Ta \&St
                    183: .It Li 0x0000000200000000ULL Ta \&Sy
                    184: .It Li 0x0000000400000000ULL Ta \&Tn
                    185: .It Li 0x0000000800000000ULL Ta \&Va
                    186: .It Li 0x0000001000000000ULL Ta \&Vt
                    187: .It Li 0x0000002000000000ULL Ta \&Xr
1.1       schwarze  188: .El
                    189: .Pp
                    190: The last four bytes are a host-ordered record number within the
                    191: .Sx Index Database .
                    192: .Sh IMPLEMENTATION NOTES
                    193: The time to construct a new database pair grows linearly with the
1.3       kristaps  194: number of keywords in the input files.
1.1       schwarze  195: However, removing or updating entries with
1.3       kristaps  196: .Fl u
1.1       schwarze  197: or
1.3       kristaps  198: .Fl d ,
1.1       schwarze  199: respectively, grows as a multiple of the index length and input size.
                    200: .Sh FILES
                    201: .Bl -tag -width Ds
                    202: .It Pa mandoc.db
                    203: A
                    204: .Xr btree 3
                    205: keyword database mapping keywords to a type and file reference in
                    206: .Pa mandoc.index .
                    207: .It Pa mandoc.index
                    208: A
                    209: .Xr recno 3
                    210: database of indexed file-names.
                    211: .El
                    212: .Sh EXIT STATUS
                    213: The
                    214: .Nm
                    215: utility exits with one of the following values:
                    216: .Pp
                    217: .Bl -tag -width Ds -compact
                    218: .It 0
                    219: No errors occurred.
                    220: .It 5
                    221: Invalid command line arguments were specified.
                    222: No input files have been read.
                    223: .It 6
                    224: An operating system error occurred, for example memory exhaustion or an
                    225: error accessing input files.
                    226: Such errors cause
                    227: .Nm
                    228: to exit at once, possibly in the middle of parsing or formatting a file.
                    229: The output databases are corrupt and should be removed .
1.10      kristaps  230: .El
                    231: .Sh DIAGNOSTICS
                    232: If the following errors occur, the
                    233: .Nm
                    234: databases should be rebuilt.
                    235: .Bl -diag
                    236: .It "%s: Corrupt database"
                    237: The keyword database file indicated by
                    238: .Pa %s
                    239: is unreadable.
                    240: .It "%s: Corrupt index"
                    241: The index database file indicated by
                    242: .Pa %s
                    243: is unreadable.
                    244: .It "%s: Path too long"
                    245: The file
                    246: .Pa %s
                    247: is too long.
                    248: This usually indicates database corruption or invalid command-line
                    249: arguments.
1.1       schwarze  250: .El
                    251: .Sh SEE ALSO
1.6       kristaps  252: .Xr man 1 ,
1.3       kristaps  253: .Xr btree 3 ,
                    254: .Xr recno 3
1.1       schwarze  255: .Sh AUTHORS
                    256: The
                    257: .Nm
                    258: utility was written by
1.4       kristaps  259: .An Kristaps Dzonsons ,
                    260: .Mt kristaps@bsd.lv .

CVSweb