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

Annotation of mandoc/makewhatis.8, Revision 1.5

1.5     ! schwarze    1: .\"    $Id: makewhatis.8,v 1.4 2016/07/19 22:40:33 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.5     ! schwarze   18: .Dd $Mdocdate: July 19 2016 $
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.
                     77: If
                     78: .Ar dir
                     79: is not provided,
                     80: .Nm
                     81: uses the default paths stipulated by
                     82: .Xr man.conf 5 .
                     83: .Pp
                     84: The arguments are as follows:
                     85: .Bl -tag -width "-C file"
                     86: .It Fl a
                     87: Use all directories and files found below
                     88: .Ar dir ... .
                     89: .It Fl C Ar file
                     90: Specify an alternative configuration
                     91: .Ar file
                     92: in
                     93: .Xr man.conf 5
                     94: format.
                     95: .It Fl D
                     96: Display all files added or removed to the index.
                     97: With a second
                     98: .Fl D ,
1.3       schwarze   99: also show all keywords added for each file.
1.1       schwarze  100: .It Fl d Ar dir
                    101: Merge (remove and re-add)
                    102: .Ar
                    103: to the database in
                    104: .Ar dir .
                    105: .It Fl n
                    106: Do not create or modify any database; scan and parse only,
                    107: and print manual page names and descriptions to standard output.
                    108: .It Fl p
                    109: Print warnings about potential problems with manual pages
                    110: to the standard error output.
                    111: .It Fl Q
                    112: Quickly build reduced-size databases
                    113: by reading only the NAME sections of manuals.
                    114: The resulting databases will usually contain names and descriptions only.
                    115: .It Fl T Cm utf8
                    116: Use UTF-8 encoding instead of ASCII for strings stored in the databases.
                    117: .It Fl t Ar
                    118: Check the given
                    119: .Ar files
                    120: for potential problems.
                    121: Implies
                    122: .Fl a ,
                    123: .Fl n ,
                    124: and
                    125: .Fl p .
                    126: All diagnostic messages are printed to the standard output;
                    127: the standard error output is not used.
                    128: .It Fl u Ar dir
                    129: Remove
                    130: .Ar
                    131: from the database in
                    132: .Ar dir .
                    133: .El
                    134: .Pp
                    135: If fatal parse errors are encountered while parsing, the offending file
                    136: is printed to stderr, omitted from the index, and the parse continues
                    137: with the next input file.
1.5     ! schwarze  138: .Sh ENVIRONMENT
        !           139: .Bl -tag -width MANPATH
        !           140: .It Ev MANPATH
        !           141: A colon-separated list of directories to create databases in.
        !           142: Ignored if a
        !           143: .Ar dir
        !           144: argument or the
        !           145: .Fl t
        !           146: option is specified.
        !           147: .El
1.1       schwarze  148: .Sh FILES
                    149: .Bl -tag -width Ds
                    150: .It Pa mandoc.db
                    151: A database of manpages relative to the directory of the file.
                    152: This file is portable across architectures and systems, so long as the
                    153: manpage hierarchy it indexes does not change.
                    154: .It Pa /etc/man.conf
                    155: The default
                    156: .Xr man 1
                    157: configuration file.
                    158: .El
                    159: .Sh EXIT STATUS
                    160: The
                    161: .Nm
                    162: utility exits with one of the following values:
                    163: .Pp
                    164: .Bl -tag -width Ds -compact
                    165: .It 0
                    166: No errors occurred.
                    167: .It 5
                    168: Invalid command line arguments were specified.
                    169: No input files have been read.
                    170: .It 6
                    171: An operating system error occurred, for example memory exhaustion or an
                    172: error accessing input files.
                    173: Such errors cause
                    174: .Nm
                    175: to exit at once, possibly in the middle of parsing or formatting a file.
                    176: The output databases are corrupt and should be removed.
                    177: .El
                    178: .Sh SEE ALSO
                    179: .Xr apropos 1 ,
                    180: .Xr man 1 ,
                    181: .Xr whatis 1 ,
                    182: .Xr man.conf 5
                    183: .Sh HISTORY
                    184: A
                    185: .Nm
                    186: utility first appeared in
                    187: .Bx 2 .
                    188: It was rewritten in
                    189: .Xr perl 1
                    190: for
                    191: .Ox 2.7
                    192: and in C for
                    193: .Ox 5.6 .
                    194: .Pp
                    195: The
                    196: .Ar dir
                    197: argument first appeared in
                    198: .Nx 1.0 ;
                    199: the options
                    200: .Fl dpt
                    201: in
                    202: .Ox 2.7 ;
                    203: the option
                    204: .Fl u
                    205: in
                    206: .Ox 3.4 ;
                    207: and the options
                    208: .Fl aCDnQT
                    209: in
                    210: .Ox 5.6 .
                    211: .Sh AUTHORS
                    212: .An -nosplit
                    213: .An Bill Joy
                    214: wrote the original
                    215: .Bx
                    216: .Nm
                    217: in February 1979,
                    218: .An Marc Espie
                    219: started the Perl version in 2000,
                    220: and the current version of
                    221: .Nm
                    222: was written by
                    223: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
                    224: and
                    225: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .

CVSweb