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

Annotation of mandoc/mandocdb.8, Revision 1.9

1.9     ! kristaps    1: .\"    $Id: mandocdb.8,v 1.8 2011/11/28 01:37:34 schwarze 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.9     ! kristaps   17: .Dd $Mdocdate: November 28 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
                     89: Verbose operation.
                     90: Use once to display all files added or removed and twice for keywords as
                     91: well.
1.1       schwarze   92: .El
                     93: .Pp
1.2       kristaps   94: If fatal parse errors are encountered while parsing, the offending file
                     95: is printed to stderr, omitted from the index, and the parse continues
                     96: with the next input file.
1.1       schwarze   97: .Ss Index Database
                     98: The index database,
                     99: .Pa mandoc.index ,
                    100: is a
                    101: .Xr recno 3
                    102: database with record values consisting of
                    103: .Pp
                    104: .Bl -enum -compact
                    105: .It
1.8       schwarze  106: the string
                    107: .Cm mdoc ,
                    108: .Cm man ,
                    109: or
                    110: .Cm cat
1.9     ! kristaps  111: to indicate the file type
        !           112: .Po
        !           113: file in
        !           114: .Xr mdoc 7 ,
        !           115: .Xr man 7 ,
        !           116: and post-formatted, respectively
        !           117: .Pc ,
1.1       schwarze  118: .It
1.8       schwarze  119: the filename,
1.1       schwarze  120: .It
1.8       schwarze  121: the manual section,
1.1       schwarze  122: .It
1.8       schwarze  123: the manual title,
1.1       schwarze  124: .It
1.8       schwarze  125: the architecture
                    126: .Pq often empty ,
                    127: .It
                    128: and the description.
1.1       schwarze  129: .El
                    130: .Pp
1.8       schwarze  131: Each of the above is NUL-terminated.
                    132: .Pp
1.3       kristaps  133: Both the manual section and description may be zero-length if the record
                    134: is unassigned.
1.1       schwarze  135: Entries are sequentially-numbered, but the filenames are unordered.
                    136: .Ss Keyword Database
                    137: The keyword database,
                    138: .Pa mandoc.db ,
                    139: is a
                    140: .Xr btree 3
1.8       schwarze  141: database of NUL-terminated keywords (record length is non-zero string
1.1       schwarze  142: length plus one) mapping to a 8-byte binary field consisting of the
                    143: keyword type and source
                    144: .Sx Index Database
                    145: record number.
1.9     ! kristaps  146: The type, a 64-bit bit-mask in host order, consists of the following
        !           147: values mapping into
        !           148: .Xr mdoc 7
        !           149: macro identifiers:
        !           150: .Pp
        !           151: .Bl -column "x0x0000000000000001ULLx" "xLix" -offset indent -compact
        !           152: .It Li 0x0000000000000001ULL Ta \&An
        !           153: .It Li 0x0000000000000002ULL Ta \&Ar
        !           154: .It Li 0x0000000000000004ULL Ta \&At
        !           155: .It Li 0x0000000000000008ULL Ta \&Bsx
        !           156: .It Li 0x0000000000000010ULL Ta \&Bx
        !           157: .It Li 0x0000000000000020ULL Ta \&Cd
        !           158: .It Li 0x0000000000000040ULL Ta \&Cm
        !           159: .It Li 0x0000000000000080ULL Ta \&Dv
        !           160: .It Li 0x0000000000000100ULL Ta \&Dx
        !           161: .It Li 0x0000000000000200ULL Ta \&Em
        !           162: .It Li 0x0000000000000400ULL Ta \&Er
        !           163: .It Li 0x0000000000000800ULL Ta \&Ev
        !           164: .It Li 0x0000000000001000ULL Ta \&Fa
        !           165: .It Li 0x0000000000002000ULL Ta \&Fl
        !           166: .It Li 0x0000000000004000ULL Ta \&Fn
        !           167: .It Li 0x0000000000008000ULL Ta \&Ft
        !           168: .It Li 0x0000000000010000ULL Ta \&Fx
        !           169: .It Li 0x0000000000020000ULL Ta \&Ic
        !           170: .It Li 0x0000000000040000ULL Ta \&In
        !           171: .It Li 0x0000000000080000ULL Ta \&Lb
        !           172: .It Li 0x0000000000100000ULL Ta \&Li
        !           173: .It Li 0x0000000000200000ULL Ta \&Lk
        !           174: .It Li 0x0000000000400000ULL Ta \&Ms
        !           175: .It Li 0x0000000000800000ULL Ta \&Mt
        !           176: .It Li 0x0000000001000000ULL Ta \&Nd
        !           177: .It Li 0x0000000002000000ULL Ta \&Nm
        !           178: .It Li 0x0000000004000000ULL Ta \&Nx
        !           179: .It Li 0x0000000008000000ULL Ta \&Ox
        !           180: .It Li 0x0000000010000000ULL Ta \&Pa
        !           181: .It Li 0x0000000020000000ULL Ta \&Rs
        !           182: .It Li 0x0000000040000000ULL Ta \&Sh
        !           183: .It Li 0x0000000080000000ULL Ta \&Ss
        !           184: .It Li 0x0000000100000000ULL Ta \&St
        !           185: .It Li 0x0000000200000000ULL Ta \&Sy
        !           186: .It Li 0x0000000400000000ULL Ta \&Tn
        !           187: .It Li 0x0000000800000000ULL Ta \&Va
        !           188: .It Li 0x0000001000000000ULL Ta \&Vt
        !           189: .It Li 0x0000002000000000ULL Ta \&Xr
1.1       schwarze  190: .El
                    191: .Pp
                    192: The last four bytes are a host-ordered record number within the
                    193: .Sx Index Database .
                    194: .Sh IMPLEMENTATION NOTES
                    195: The time to construct a new database pair grows linearly with the
1.3       kristaps  196: number of keywords in the input files.
1.1       schwarze  197: However, removing or updating entries with
1.3       kristaps  198: .Fl u
1.1       schwarze  199: or
1.3       kristaps  200: .Fl d ,
1.1       schwarze  201: respectively, grows as a multiple of the index length and input size.
                    202: .Sh FILES
                    203: .Bl -tag -width Ds
                    204: .It Pa mandoc.db
                    205: A
                    206: .Xr btree 3
                    207: keyword database mapping keywords to a type and file reference in
                    208: .Pa mandoc.index .
                    209: .It Pa mandoc.index
                    210: A
                    211: .Xr recno 3
                    212: database of indexed file-names.
                    213: .El
                    214: .Sh EXIT STATUS
                    215: The
                    216: .Nm
                    217: utility exits with one of the following values:
                    218: .Pp
                    219: .Bl -tag -width Ds -compact
                    220: .It 0
                    221: No errors occurred.
                    222: .It 5
                    223: Invalid command line arguments were specified.
                    224: No input files have been read.
                    225: .It 6
                    226: An operating system error occurred, for example memory exhaustion or an
                    227: error accessing input files.
                    228: Such errors cause
                    229: .Nm
                    230: to exit at once, possibly in the middle of parsing or formatting a file.
                    231: The output databases are corrupt and should be removed .
                    232: .El
                    233: .Sh SEE ALSO
1.6       kristaps  234: .Xr man 1 ,
1.3       kristaps  235: .Xr btree 3 ,
                    236: .Xr recno 3
1.1       schwarze  237: .Sh AUTHORS
                    238: The
                    239: .Nm
                    240: utility was written by
1.4       kristaps  241: .An Kristaps Dzonsons ,
                    242: .Mt kristaps@bsd.lv .

CVSweb