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

Annotation of mandoc/makewhatis.8, Revision 1.6

1.6     ! schwarze    1: .\"    $Id: makewhatis.8,v 1.5 2017/03/18 19:51:19 schwarze Exp $
1.1       schwarze    2: .\"
                      3: .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
1.5       schwarze    4: .\" Copyright (c) 2011, 2012, 2014, 2017 Ingo Schwarze <schwarze@openbsd.org>
1.1       schwarze    5: .\"
                      6: .\" Permission to use, copy, modify, and distribute this software for any
                      7: .\" purpose with or without fee is hereby granted, provided that the above
                      8: .\" copyright notice and this permission notice appear in all copies.
                      9: .\"
                     10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
                     11: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
                     12: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
                     13: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     14: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
                     15: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
                     16: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
                     17: .\"
1.6     ! schwarze   18: .Dd $Mdocdate: March 18 2017 $
1.1       schwarze   19: .Dt MAKEWHATIS 8
                     20: .Os
                     21: .Sh NAME
                     22: .Nm makewhatis
                     23: .Nd index UNIX manuals
                     24: .Sh SYNOPSIS
                     25: .Nm
                     26: .Op Fl aDnpQ
                     27: .Op Fl T Cm utf8
                     28: .Op Fl C Ar file
                     29: .Nm
                     30: .Op Fl aDnpQ
                     31: .Op Fl T Cm utf8
                     32: .Ar dir ...
                     33: .Nm
                     34: .Op Fl DnpQ
                     35: .Op Fl T Cm utf8
                     36: .Fl d Ar dir
                     37: .Op Ar
                     38: .Nm
                     39: .Op Fl Dnp
                     40: .Op Fl T Cm utf8
                     41: .Fl u Ar dir
                     42: .Op Ar
                     43: .Nm
1.2       schwarze   44: .Op Fl DQ
1.1       schwarze   45: .Fl t Ar
                     46: .Sh DESCRIPTION
                     47: The
                     48: .Nm
                     49: utility extracts keywords from
                     50: .Ux
                     51: manuals and indexes them in a database for fast retrieval by
                     52: .Xr apropos 1 ,
                     53: .Xr whatis 1 ,
                     54: and
                     55: .Xr man 1 Ns 's
                     56: .Fl k
                     57: option.
                     58: .Pp
                     59: By default,
                     60: .Nm
                     61: creates a database in each
                     62: .Ar dir
                     63: using the files
                     64: .Sm off
                     65: .Sy man Ar section Li /
                     66: .Op Ar arch Li /
                     67: .Ar title . section
                     68: .Sm on
                     69: and
                     70: .Sm off
                     71: .Sy cat Ar section Li /
                     72: .Op Ar arch Li /
                     73: .Ar title . Sy 0
                     74: .Sm on
                     75: in that directory.
                     76: Existing databases are replaced.
1.6     ! schwarze   77: If a directory contains no manual pages, no database is created in that
        !            78: directory.
1.1       schwarze   79: If
                     80: .Ar dir
                     81: is not provided,
                     82: .Nm
                     83: uses the default paths stipulated by
                     84: .Xr man.conf 5 .
                     85: .Pp
                     86: The arguments are as follows:
                     87: .Bl -tag -width "-C file"
                     88: .It Fl a
                     89: Use all directories and files found below
                     90: .Ar dir ... .
                     91: .It Fl C Ar file
                     92: Specify an alternative configuration
                     93: .Ar file
                     94: in
                     95: .Xr man.conf 5
                     96: format.
                     97: .It Fl D
                     98: Display all files added or removed to the index.
                     99: With a second
                    100: .Fl D ,
1.3       schwarze  101: also show all keywords added for each file.
1.1       schwarze  102: .It Fl d Ar dir
                    103: Merge (remove and re-add)
                    104: .Ar
                    105: to the database in
                    106: .Ar dir .
                    107: .It Fl n
                    108: Do not create or modify any database; scan and parse only,
                    109: and print manual page names and descriptions to standard output.
                    110: .It Fl p
                    111: Print warnings about potential problems with manual pages
                    112: to the standard error output.
                    113: .It Fl Q
                    114: Quickly build reduced-size databases
                    115: by reading only the NAME sections of manuals.
                    116: The resulting databases will usually contain names and descriptions only.
                    117: .It Fl T Cm utf8
                    118: Use UTF-8 encoding instead of ASCII for strings stored in the databases.
                    119: .It Fl t Ar
                    120: Check the given
                    121: .Ar files
                    122: for potential problems.
                    123: Implies
                    124: .Fl a ,
                    125: .Fl n ,
                    126: and
                    127: .Fl p .
                    128: All diagnostic messages are printed to the standard output;
                    129: the standard error output is not used.
                    130: .It Fl u Ar dir
                    131: Remove
                    132: .Ar
                    133: from the database in
                    134: .Ar dir .
1.6     ! schwarze  135: If that causes the database to become empty, also delete the database file.
1.1       schwarze  136: .El
                    137: .Pp
                    138: If fatal parse errors are encountered while parsing, the offending file
                    139: is printed to stderr, omitted from the index, and the parse continues
                    140: with the next input file.
1.5       schwarze  141: .Sh ENVIRONMENT
                    142: .Bl -tag -width MANPATH
                    143: .It Ev MANPATH
                    144: A colon-separated list of directories to create databases in.
                    145: Ignored if a
                    146: .Ar dir
                    147: argument or the
                    148: .Fl t
                    149: option is specified.
                    150: .El
1.1       schwarze  151: .Sh FILES
                    152: .Bl -tag -width Ds
                    153: .It Pa mandoc.db
                    154: A database of manpages relative to the directory of the file.
                    155: This file is portable across architectures and systems, so long as the
                    156: manpage hierarchy it indexes does not change.
                    157: .It Pa /etc/man.conf
                    158: The default
                    159: .Xr man 1
                    160: configuration file.
                    161: .El
                    162: .Sh EXIT STATUS
                    163: The
                    164: .Nm
                    165: utility exits with one of the following values:
                    166: .Pp
                    167: .Bl -tag -width Ds -compact
                    168: .It 0
                    169: No errors occurred.
                    170: .It 5
                    171: Invalid command line arguments were specified.
                    172: No input files have been read.
                    173: .It 6
                    174: An operating system error occurred, for example memory exhaustion or an
                    175: error accessing input files.
                    176: Such errors cause
                    177: .Nm
                    178: to exit at once, possibly in the middle of parsing or formatting a file.
                    179: The output databases are corrupt and should be removed.
                    180: .El
                    181: .Sh SEE ALSO
                    182: .Xr apropos 1 ,
                    183: .Xr man 1 ,
                    184: .Xr whatis 1 ,
                    185: .Xr man.conf 5
                    186: .Sh HISTORY
                    187: A
                    188: .Nm
                    189: utility first appeared in
                    190: .Bx 2 .
                    191: It was rewritten in
                    192: .Xr perl 1
                    193: for
                    194: .Ox 2.7
                    195: and in C for
                    196: .Ox 5.6 .
                    197: .Pp
                    198: The
                    199: .Ar dir
                    200: argument first appeared in
                    201: .Nx 1.0 ;
                    202: the options
                    203: .Fl dpt
                    204: in
                    205: .Ox 2.7 ;
                    206: the option
                    207: .Fl u
                    208: in
                    209: .Ox 3.4 ;
                    210: and the options
                    211: .Fl aCDnQT
                    212: in
                    213: .Ox 5.6 .
                    214: .Sh AUTHORS
                    215: .An -nosplit
                    216: .An Bill Joy
                    217: wrote the original
                    218: .Bx
                    219: .Nm
                    220: in February 1979,
                    221: .An Marc Espie
                    222: started the Perl version in 2000,
                    223: and the current version of
                    224: .Nm
                    225: was written by
                    226: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
                    227: and
                    228: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .

CVSweb