Annotation of mandoc/makewhatis.8, Revision 1.1
1.1 ! schwarze 1: .\" $Id: mandocdb.8,v 1.25 2014/04/04 02:31:07 schwarze Exp $
! 2: .\"
! 3: .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
! 4: .\" Copyright (c) 2011, 2012 Ingo Schwarze <schwarze@openbsd.org>
! 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: .\"
! 18: .Dd $Mdocdate: April 4 2014 $
! 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
! 44: .Op Fl Q
! 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 manpath 1 ,
! 83: or
! 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 ,
! 101: also show all keyswords added for each file.
! 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 .
! 135: .El
! 136: .Pp
! 137: If fatal parse errors are encountered while parsing, the offending file
! 138: is printed to stderr, omitted from the index, and the parse continues
! 139: with the next input file.
! 140: .Sh FILES
! 141: .Bl -tag -width Ds
! 142: .It Pa mandoc.db
! 143: A database of manpages relative to the directory of the file.
! 144: This file is portable across architectures and systems, so long as the
! 145: manpage hierarchy it indexes does not change.
! 146: .It Pa /etc/man.conf
! 147: The default
! 148: .Xr man 1
! 149: configuration file.
! 150: .El
! 151: .Sh EXIT STATUS
! 152: The
! 153: .Nm
! 154: utility exits with one of the following values:
! 155: .Pp
! 156: .Bl -tag -width Ds -compact
! 157: .It 0
! 158: No errors occurred.
! 159: .It 5
! 160: Invalid command line arguments were specified.
! 161: No input files have been read.
! 162: .It 6
! 163: An operating system error occurred, for example memory exhaustion or an
! 164: error accessing input files.
! 165: Such errors cause
! 166: .Nm
! 167: to exit at once, possibly in the middle of parsing or formatting a file.
! 168: The output databases are corrupt and should be removed.
! 169: .El
! 170: .Sh SEE ALSO
! 171: .Xr apropos 1 ,
! 172: .Xr man 1 ,
! 173: .Xr whatis 1 ,
! 174: .Xr man.conf 5
! 175: .Sh HISTORY
! 176: A
! 177: .Nm
! 178: utility first appeared in
! 179: .Bx 2 .
! 180: It was rewritten in
! 181: .Xr perl 1
! 182: for
! 183: .Ox 2.7
! 184: and in C for
! 185: .Ox 5.6 .
! 186: .Pp
! 187: The
! 188: .Ar dir
! 189: argument first appeared in
! 190: .Nx 1.0 ;
! 191: the options
! 192: .Fl dpt
! 193: in
! 194: .Ox 2.7 ;
! 195: the option
! 196: .Fl u
! 197: in
! 198: .Ox 3.4 ;
! 199: and the options
! 200: .Fl aCDnQT
! 201: in
! 202: .Ox 5.6 .
! 203: .Sh AUTHORS
! 204: .An -nosplit
! 205: .An Bill Joy
! 206: wrote the original
! 207: .Bx
! 208: .Nm
! 209: in February 1979,
! 210: .An Marc Espie
! 211: started the Perl version in 2000,
! 212: and the current version of
! 213: .Nm
! 214: was written by
! 215: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
! 216: and
! 217: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
CVSweb