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

Annotation of mandoc/mandocdb.8, Revision 1.7

1.7     ! schwarze    1: .\"    $Id: mandocdb.8,v 1.6 2011/11/23 09:52:20 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.7     ! schwarze   17: .Dd $Mdocdate: November 23 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.3       kristaps   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.7     ! schwarze   45: .Pp
1.1       schwarze   46: The arguments are as follows:
                     47: .Bl -tag -width Ds
1.7     ! schwarze   48: .It Fl a
        !            49: Use all directories and files found below
        !            50: .Ar dir ... .
        !            51: By default, only files matching
        !            52: .Sm off
        !            53: .Sy man Ar section Li /
        !            54: .Op Ar arch Li /
        !            55: .Ar title . section
        !            56: .Sm on
        !            57: will be used.
1.3       kristaps   58: .It Fl d Ar dir
1.5       kristaps   59: Merge (remove and re-add)
1.3       kristaps   60: .Ar
                     61: from the databases in
                     62: .Ar dir .
                     63: .It Fl u Ar dir
1.5       kristaps   64: Remove
1.3       kristaps   65: .Ar
                     66: from the databases in
                     67: .Ar dir .
1.2       kristaps   68: .It Ar dir...
1.3       kristaps   69: Recursively add files rooted at each
1.2       kristaps   70: .Ar dir
1.3       kristaps   71: to the databases in the respective
                     72: .Ar dir .
1.2       kristaps   73: Existing databases are truncated.
1.3       kristaps   74: .It Fl v
                     75: Verbose operation.
                     76: Use once to display all files added or removed and twice for keywords as
                     77: well.
1.1       schwarze   78: .El
                     79: .Pp
                     80: By default,
                     81: .Nm
1.3       kristaps   82: creates databases in each
                     83: .Ar dir
                     84: using files rooted in that directory.
1.6       kristaps   85: If
                     86: .Ar dir
                     87: is not provided,
                     88: .Nm
                     89: uses the default paths stipulated by
                     90: .Xr man 1 .
1.1       schwarze   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
                    104: a nil-terminated filename,
                    105: .It
                    106: a nil-terminated manual section,
                    107: .It
                    108: a nil-terminated manual title,
                    109: .It
                    110: a nil-terminated architecture
                    111: .Pq this is not often available
                    112: .It
                    113: and a nil-terminated description.
                    114: .El
                    115: .Pp
1.3       kristaps  116: Both the manual section and description may be zero-length if the record
                    117: is unassigned.
1.1       schwarze  118: Entries are sequentially-numbered, but the filenames are unordered.
                    119: .Ss Keyword Database
                    120: The keyword database,
                    121: .Pa mandoc.db ,
                    122: is a
                    123: .Xr btree 3
                    124: database of nil-terminated keywords (record length is non-zero string
                    125: length plus one) mapping to a 8-byte binary field consisting of the
                    126: keyword type and source
                    127: .Sx Index Database
                    128: record number.
                    129: The type, a 32-bit bit-mask in host order, consists of the following
                    130: fields:
                    131: .Pp
                    132: .Bl -tag -width Ds -offset indent -compact
                    133: .It Li 0x01
                    134: The name of a manual page as given in the NAME section.
                    135: .It Li 0x02
                    136: A function prototype name as given in the SYNOPSIS section.
                    137: .It Li 0x04
                    138: A utility name as given in the SYNOPSIS section.
                    139: .It Li 0x08
                    140: An include file as given in the SYNOPSIS section.
                    141: .It Li 0x10
                    142: A variable name as given in the SYNOPSIS section.
                    143: .It Li 0x20
                    144: A standard as given in the STANDARDS section.
                    145: .It Li 0x40
                    146: An author as given in the AUTHORS section.
                    147: .It Li 0x80
                    148: A configuration as given in the SYNOPSIS section.
                    149: .It Li 0x100
                    150: Free-form descriptive text as given in the NAME section.
                    151: .It Li 0x200
                    152: Cross-links between manuals.
                    153: Listed as the link name, then a period, then the link section.
                    154: If the link has no section, the period terminates the string.
                    155: .It Li 0x400
                    156: Path reference as given in the FILES section.
                    157: .It Li 0x800
                    158: Environment variable as given in the ENVIRONMENT section.
                    159: .It Li 0x1000
                    160: Error codes as given in the ERRORS section.
                    161: .El
                    162: .Pp
                    163: The last four bytes are a host-ordered record number within the
                    164: .Sx Index Database .
                    165: .Pp
                    166: The
                    167: .Nm
                    168: utility is
                    169: .Ud
                    170: .Sh IMPLEMENTATION NOTES
                    171: The time to construct a new database pair grows linearly with the
1.3       kristaps  172: number of keywords in the input files.
1.1       schwarze  173: However, removing or updating entries with
1.3       kristaps  174: .Fl u
1.1       schwarze  175: or
1.3       kristaps  176: .Fl d ,
1.1       schwarze  177: respectively, grows as a multiple of the index length and input size.
                    178: .Sh FILES
                    179: .Bl -tag -width Ds
                    180: .It Pa mandoc.db
                    181: A
                    182: .Xr btree 3
                    183: keyword database mapping keywords to a type and file reference in
                    184: .Pa mandoc.index .
                    185: .It Pa mandoc.index
                    186: A
                    187: .Xr recno 3
                    188: database of indexed file-names.
                    189: .El
                    190: .Sh EXIT STATUS
                    191: The
                    192: .Nm
                    193: utility exits with one of the following values:
                    194: .Pp
                    195: .Bl -tag -width Ds -compact
                    196: .It 0
                    197: No errors occurred.
                    198: .It 5
                    199: Invalid command line arguments were specified.
                    200: No input files have been read.
                    201: .It 6
                    202: An operating system error occurred, for example memory exhaustion or an
                    203: error accessing input files.
                    204: Such errors cause
                    205: .Nm
                    206: to exit at once, possibly in the middle of parsing or formatting a file.
                    207: The output databases are corrupt and should be removed .
                    208: .El
                    209: .Sh SEE ALSO
1.6       kristaps  210: .Xr man 1 ,
1.3       kristaps  211: .Xr mandoc 1 ,
                    212: .Xr btree 3 ,
                    213: .Xr recno 3
1.1       schwarze  214: .Sh AUTHORS
                    215: The
                    216: .Nm
                    217: utility was written by
1.4       kristaps  218: .An Kristaps Dzonsons ,
                    219: .Mt kristaps@bsd.lv .

CVSweb