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

Annotation of mandoc/mandocdb.8, Revision 1.17.2.1

1.17.2.1! schwarze    1: .\"    $Id: mandocdb.8,v 1.17 2011/12/25 21:00:23 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.16      schwarze   17: .Dd $Mdocdate: December 25 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.15      schwarze   25: .Op Fl avW
1.12      schwarze   26: .Op Fl C Ar file
                     27: .Nm
1.15      schwarze   28: .Op Fl avW
1.12      schwarze   29: .Ar dir ...
1.3       kristaps   30: .Nm
1.15      schwarze   31: .Op Fl vW
1.3       kristaps   32: .Fl d Ar dir
                     33: .Op Ar
                     34: .Nm
1.15      schwarze   35: .Op Fl vW
1.3       kristaps   36: .Fl u Ar dir
                     37: .Op Ar
1.15      schwarze   38: .Nm
                     39: .Fl t Ar
1.1       schwarze   40: .Sh DESCRIPTION
                     41: The
                     42: .Nm
                     43: utility extracts keywords from
                     44: .Ux
1.3       kristaps   45: manuals and indexes them in a
                     46: .Sx Keyword Database
                     47: and
                     48: .Sx Index Database
1.17      schwarze   49: for fast retrieval by
                     50: .Xr apropos 1 ,
                     51: .Xr whatis 1 ,
                     52: and
                     53: .Xr man 1 Ns 's
                     54: .Fl k
                     55: option.
1.7       schwarze   56: .Pp
1.8       schwarze   57: By default,
                     58: .Nm
                     59: creates databases in each
                     60: .Ar dir
                     61: using the files
                     62: .Sm off
                     63: .Sy man Ar section Li /
                     64: .Op Ar arch Li /
                     65: .Ar title . section
                     66: .Sm on
                     67: and
                     68: .Sm off
                     69: .Sy cat Ar section Li /
                     70: .Op Ar arch Li /
                     71: .Ar title . Sy 0
                     72: .Sm on
                     73: in that directory;
                     74: existing databases are truncated.
                     75: If
                     76: .Ar dir
                     77: is not provided,
                     78: .Nm
                     79: uses the default paths stipulated by
                     80: .Xr man 1 .
                     81: .Pp
1.1       schwarze   82: The arguments are as follows:
1.12      schwarze   83: .Bl -tag -width "-C file"
1.7       schwarze   84: .It Fl a
                     85: Use all directories and files found below
                     86: .Ar dir ... .
1.12      schwarze   87: .It Fl C Ar file
                     88: Specify an alternative configuration
                     89: .Ar file
                     90: in
                     91: .Xr man.conf 5
                     92: format.
1.3       kristaps   93: .It Fl d Ar dir
1.5       kristaps   94: Merge (remove and re-add)
1.3       kristaps   95: .Ar
1.8       schwarze   96: to the database in
                     97: .Ar dir
                     98: without truncating it.
1.15      schwarze   99: .It Fl t Ar
                    100: Check the given
                    101: .Ar files
                    102: for potential problems.
                    103: No databases are modified.
                    104: Implies
                    105: .Fl a
                    106: and
                    107: .Fl W .
                    108: All diagnostic messages are printed to the standard output;
                    109: the standard error output is not used.
1.3       kristaps  110: .It Fl u Ar dir
1.5       kristaps  111: Remove
1.3       kristaps  112: .Ar
1.8       schwarze  113: from the database in
1.2       kristaps  114: .Ar dir
1.8       schwarze  115: without truncating it.
1.3       kristaps  116: .It Fl v
1.10      kristaps  117: Display all files added or removed to the index.
1.15      schwarze  118: .It Fl W
                    119: Print warnings about potential problems with manual pages
                    120: to the standard error output.
1.1       schwarze  121: .El
                    122: .Pp
1.2       kristaps  123: If fatal parse errors are encountered while parsing, the offending file
                    124: is printed to stderr, omitted from the index, and the parse continues
                    125: with the next input file.
1.1       schwarze  126: .Ss Index Database
                    127: The index database,
1.17.2.1! schwarze  128: .Pa mandoc.index ,
1.1       schwarze  129: is a
                    130: .Xr recno 3
                    131: database with record values consisting of
                    132: .Pp
                    133: .Bl -enum -compact
                    134: .It
1.14      kristaps  135: the character
                    136: .Cm d ,
                    137: .Cm a ,
1.8       schwarze  138: or
1.14      kristaps  139: .Cm c
1.9       kristaps  140: to indicate the file type
                    141: .Po
                    142: .Xr mdoc 7 ,
                    143: .Xr man 7 ,
                    144: and post-formatted, respectively
                    145: .Pc ,
1.1       schwarze  146: .It
1.13      kristaps  147: the filename relative to the databases' path,
1.1       schwarze  148: .It
1.8       schwarze  149: the manual section,
1.1       schwarze  150: .It
1.8       schwarze  151: the manual title,
1.1       schwarze  152: .It
1.8       schwarze  153: the architecture
                    154: .Pq often empty ,
                    155: .It
                    156: and the description.
1.1       schwarze  157: .El
                    158: .Pp
1.8       schwarze  159: Each of the above is NUL-terminated.
                    160: .Pp
1.14      kristaps  161: If the record value is zero-length, it is unassigned.
1.1       schwarze  162: .Ss Keyword Database
                    163: The keyword database,
1.17.2.1! schwarze  164: .Pa mandoc.db ,
1.1       schwarze  165: is a
                    166: .Xr btree 3
1.8       schwarze  167: database of NUL-terminated keywords (record length is non-zero string
1.17      schwarze  168: length plus one) mapping to a 16-byte binary field consisting of the
                    169: 64-bit keyword type and the 64-bit
1.1       schwarze  170: .Sx Index Database
1.11      kristaps  171: record number, both in network-byte order.
1.17      schwarze  172: .Pp
1.12      schwarze  173: The type bit-mask consists of the following
1.9       kristaps  174: values mapping into
                    175: .Xr mdoc 7
                    176: macro identifiers:
                    177: .Pp
                    178: .Bl -column "x0x0000000000000001ULLx" "xLix" -offset indent -compact
                    179: .It Li 0x0000000000000001ULL Ta \&An
                    180: .It Li 0x0000000000000002ULL Ta \&Ar
                    181: .It Li 0x0000000000000004ULL Ta \&At
                    182: .It Li 0x0000000000000008ULL Ta \&Bsx
                    183: .It Li 0x0000000000000010ULL Ta \&Bx
                    184: .It Li 0x0000000000000020ULL Ta \&Cd
                    185: .It Li 0x0000000000000040ULL Ta \&Cm
                    186: .It Li 0x0000000000000080ULL Ta \&Dv
                    187: .It Li 0x0000000000000100ULL Ta \&Dx
                    188: .It Li 0x0000000000000200ULL Ta \&Em
                    189: .It Li 0x0000000000000400ULL Ta \&Er
                    190: .It Li 0x0000000000000800ULL Ta \&Ev
                    191: .It Li 0x0000000000001000ULL Ta \&Fa
                    192: .It Li 0x0000000000002000ULL Ta \&Fl
                    193: .It Li 0x0000000000004000ULL Ta \&Fn
                    194: .It Li 0x0000000000008000ULL Ta \&Ft
                    195: .It Li 0x0000000000010000ULL Ta \&Fx
                    196: .It Li 0x0000000000020000ULL Ta \&Ic
                    197: .It Li 0x0000000000040000ULL Ta \&In
                    198: .It Li 0x0000000000080000ULL Ta \&Lb
                    199: .It Li 0x0000000000100000ULL Ta \&Li
                    200: .It Li 0x0000000000200000ULL Ta \&Lk
                    201: .It Li 0x0000000000400000ULL Ta \&Ms
                    202: .It Li 0x0000000000800000ULL Ta \&Mt
                    203: .It Li 0x0000000001000000ULL Ta \&Nd
                    204: .It Li 0x0000000002000000ULL Ta \&Nm
                    205: .It Li 0x0000000004000000ULL Ta \&Nx
                    206: .It Li 0x0000000008000000ULL Ta \&Ox
                    207: .It Li 0x0000000010000000ULL Ta \&Pa
                    208: .It Li 0x0000000020000000ULL Ta \&Rs
                    209: .It Li 0x0000000040000000ULL Ta \&Sh
                    210: .It Li 0x0000000080000000ULL Ta \&Ss
                    211: .It Li 0x0000000100000000ULL Ta \&St
                    212: .It Li 0x0000000200000000ULL Ta \&Sy
                    213: .It Li 0x0000000400000000ULL Ta \&Tn
                    214: .It Li 0x0000000800000000ULL Ta \&Va
                    215: .It Li 0x0000001000000000ULL Ta \&Vt
                    216: .It Li 0x0000002000000000ULL Ta \&Xr
1.1       schwarze  217: .El
                    218: .Sh IMPLEMENTATION NOTES
                    219: The time to construct a new database pair grows linearly with the
1.3       kristaps  220: number of keywords in the input files.
1.1       schwarze  221: However, removing or updating entries with
1.3       kristaps  222: .Fl u
1.1       schwarze  223: or
1.3       kristaps  224: .Fl d ,
1.1       schwarze  225: respectively, grows as a multiple of the index length and input size.
                    226: .Sh FILES
                    227: .Bl -tag -width Ds
1.17.2.1! schwarze  228: .It Pa mandoc.db
1.1       schwarze  229: A
                    230: .Xr btree 3
                    231: keyword database mapping keywords to a type and file reference in
1.17.2.1! schwarze  232: .Pa mandoc.index .
        !           233: .It Pa mandoc.index
1.1       schwarze  234: A
                    235: .Xr recno 3
                    236: database of indexed file-names.
1.12      schwarze  237: .It Pa /etc/man.conf
                    238: The default
                    239: .Xr man 1
                    240: configuration file.
1.1       schwarze  241: .El
                    242: .Sh EXIT STATUS
                    243: The
                    244: .Nm
                    245: utility exits with one of the following values:
                    246: .Pp
                    247: .Bl -tag -width Ds -compact
                    248: .It 0
                    249: No errors occurred.
                    250: .It 5
                    251: Invalid command line arguments were specified.
                    252: No input files have been read.
                    253: .It 6
                    254: An operating system error occurred, for example memory exhaustion or an
                    255: error accessing input files.
                    256: Such errors cause
                    257: .Nm
                    258: to exit at once, possibly in the middle of parsing or formatting a file.
1.17      schwarze  259: The output databases are corrupt and should be removed.
1.10      kristaps  260: .El
                    261: .Sh DIAGNOSTICS
                    262: If the following errors occur, the
                    263: .Nm
                    264: databases should be rebuilt.
                    265: .Bl -diag
                    266: .It "%s: Corrupt database"
                    267: The keyword database file indicated by
                    268: .Pa %s
                    269: is unreadable.
                    270: .It "%s: Corrupt index"
                    271: The index database file indicated by
                    272: .Pa %s
                    273: is unreadable.
                    274: .It "%s: Path too long"
                    275: The file
                    276: .Pa %s
                    277: is too long.
                    278: This usually indicates database corruption or invalid command-line
                    279: arguments.
1.1       schwarze  280: .El
                    281: .Sh SEE ALSO
1.12      schwarze  282: .Xr apropos 1 ,
1.6       kristaps  283: .Xr man 1 ,
1.12      schwarze  284: .Xr whatis 1 ,
1.3       kristaps  285: .Xr btree 3 ,
1.12      schwarze  286: .Xr recno 3 ,
                    287: .Xr man.conf 5
1.17.2.1! schwarze  288: .Sh HISTORY
        !           289: A
        !           290: .Nm makewhatis
        !           291: utility first appeared in
        !           292: .Bx 2 .
        !           293: It was rewritten in
        !           294: .Xr perl 1
        !           295: for
        !           296: .Ox 2.7
        !           297: and in C for
        !           298: .Ox 5.1 .
        !           299: .Pp
1.1       schwarze  300: The
1.17.2.1! schwarze  301: .Ar dir
        !           302: argument first appeared in
        !           303: .Nx 1.0 ;
        !           304: the options
        !           305: .Fl dtu
        !           306: in
        !           307: .Ox 2.7 ;
        !           308: and the options
        !           309: .Fl aCvW
        !           310: in
        !           311: .Ox 5.1 .
        !           312: .Sh AUTHORS
        !           313: .An -nosplit
        !           314: .An Bill Joy
        !           315: wrote the original
        !           316: .Bx
        !           317: .Nm makewhatis
        !           318: in February 1979,
        !           319: .An Marc Espie
        !           320: started the Perl version in 2000,
        !           321: and the current version of
1.1       schwarze  322: .Nm
1.17.2.1! schwarze  323: was written by
        !           324: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .

CVSweb