Return to makewhatis.1 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/makewhatis.1, Revision 1.8

1.8     ! kristaps    1: .\"    $Id: makewhatis.1,v 1.7 2011/06/25 13:19:25 kristaps Exp $
1.1       kristaps    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.8     ! kristaps   17: .Dd $Mdocdate: June 25 2011 $
1.2       kristaps   18: .Dt MAKEWHATIS 1
1.1       kristaps   19: .Os
                     20: .Sh NAME
                     21: .Nm makewhatis
                     22: .Nd index UNIX manuals
                     23: .Sh SYNOPSIS
                     24: .Nm
1.6       kristaps   25: .Op Fl v
1.1       kristaps   26: .Op Fl d Ar dir
                     27: .Ar
                     28: .Sh DESCRIPTION
                     29: The
                     30: .Nm
                     31: utility extracts keywords from
                     32: .Ux
                     33: manuals and indexes them for fast retrieval.
                     34: The arguments are as follows:
                     35: .Bl -tag -width Ds
                     36: .It Fl d Ar dir
                     37: The directory into which to write the keyword and index databases.
                     38: .It Ar
                     39: Read input from zero or more files in
                     40: .Xr mdoc 7
                     41: or
                     42: .Xr man 7
                     43: .Ux
                     44: manual format.
1.6       kristaps   45: .It Fl v
                     46: Verbose output.
                     47: If specified once, prints the name of each indexed file.
                     48: If twice, prints keywords for each file.
1.1       kristaps   49: .El
                     50: .Pp
                     51: By default,
                     52: .Nm
                     53: constructs the
                     54: .Sx Index Database
                     55: and
                     56: .Sx Keyword Database
                     57: in the current working directory.
                     58: .Pp
                     59: If fatal parse errors are encountered, the offending file is printed to
                     60: stderr, omitted from the index, and the parse continues with the next
                     61: input file.
                     62: .Ss Index Database
                     63: The index database,
                     64: .Pa mandoc.index ,
                     65: is a
                     66: .Xr recno 3
                     67: database with record values consisting of
                     68: .Pp
                     69: .Bl -enum -compact
                     70: .It
                     71: a nil-terminated filename,
                     72: .It
                     73: a nil-terminated manual section,
                     74: .It
                     75: a nil-terminated manual title,
                     76: .It
                     77: a nil-terminated architecture
                     78: .Pq this is not often available
                     79: .It
                     80: and a nil-terminated description.
                     81: .El
                     82: .Pp
                     83: Both the manual section and description may be zero-length.
                     84: Entries are sequentially-numbered, but the filenames are unordered.
                     85: .Ss Keyword Database
                     86: The keyword database,
                     87: .Pa mandoc.db ,
                     88: is a
                     89: .Xr btree 3
                     90: database of nil-terminated keywords (record length is non-zero string
                     91: length plus one) mapping to a 8-byte binary field consisting of the
                     92: keyword type and source
                     93: .Sx Index Database
                     94: record number.
1.4       kristaps   95: The type, a 32-bit bit-mask in host order, consists of the following
                     96: fields:
1.1       kristaps   97: .Pp
                     98: .Bl -tag -width Ds -offset indent -compact
                     99: .It Li 0x01
                    100: The name of a manual page as given in the NAME section.
                    101: .It Li 0x02
                    102: A function prototype name as given in the SYNOPSIS section.
1.4       kristaps  103: .It Li 0x04
1.1       kristaps  104: A utility name as given in the SYNOPSIS section.
1.4       kristaps  105: .It Li 0x08
1.1       kristaps  106: An include file as given in the SYNOPSIS section.
1.4       kristaps  107: .It Li 0x10
1.1       kristaps  108: A variable name as given in the SYNOPSIS section.
1.4       kristaps  109: .It Li 0x20
1.1       kristaps  110: A standard as given in the STANDARDS section.
1.4       kristaps  111: .It Li 0x40
1.1       kristaps  112: An author as given in the AUTHORS section.
1.4       kristaps  113: .It Li 0x80
1.1       kristaps  114: A configuration as given in the SYNOPSIS section.
1.5       kristaps  115: .It Li 0x100
                    116: Free-form descriptive text as given in the NAME section.
1.7       kristaps  117: .It Li 0x200
                    118: Cross-links between manuals.
                    119: Listed as the link name, then a period, then the link section.
                    120: If the link has no section, the period terminates the string.
1.8     ! kristaps  121: .It Li 0x400
        !           122: Path reference as given in the FILES section.
1.1       kristaps  123: .El
                    124: .Pp
1.4       kristaps  125: The last four bytes are a host-ordered record number within the
1.1       kristaps  126: .Sx Index Database .
                    127: .Pp
                    128: The
                    129: .Nm
                    130: utility is
                    131: .Ud
                    132: .Sh FILES
                    133: .Bl -tag -width Ds
                    134: .It Pa mandoc.db
                    135: A
                    136: .Xr btree 3
                    137: keyword database mapping keywords to a type and file reference in
                    138: .Pa mandoc.index .
                    139: .It Pa mandoc.db~
                    140: Working copy of
                    141: .Pa mandoc.db .
                    142: .It Pa mandoc.index
                    143: A
                    144: .Xr recno 3
                    145: database of indexed file-names.
                    146: .It Pa mandoc.index~
                    147: Working copy of
                    148: .Pa mandoc.index .
                    149: .El
                    150: .Sh EXIT STATUS
                    151: .Ex -std
                    152: .Sh SEE ALSO
                    153: .Xr mandoc 1
                    154: .Sh AUTHORS
                    155: The
                    156: .Nm
                    157: utility was written by
                    158: .An Kristaps Dzonsons Aq kristaps@bsd.lv .