Annotation of mandoc/mandocdb.8, Revision 1.21
1.21 ! schwarze 1: .\" $Id: mandocdb.8,v 1.20 2013/10/01 20:56:18 schwarze Exp $
1.1 schwarze 2: .\"
1.18 kristaps 3: .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
1.21 ! schwarze 4: .\" Copyright (c) 2011, 2012 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.21 ! schwarze 18: .Dd $Mdocdate: October 1 2013 $
1.1 schwarze 19: .Dt MANDOCDB 8
20: .Os
21: .Sh NAME
22: .Nm mandocdb
23: .Nd index UNIX manuals
24: .Sh SYNOPSIS
25: .Nm
1.18 kristaps 26: .Op Fl anvW
1.12 schwarze 27: .Op Fl C Ar file
28: .Nm
1.18 kristaps 29: .Op Fl anvW
1.12 schwarze 30: .Ar dir ...
1.3 kristaps 31: .Nm
1.18 kristaps 32: .Op Fl nvW
1.3 kristaps 33: .Fl d Ar dir
34: .Op Ar
35: .Nm
1.18 kristaps 36: .Op Fl nvW
1.3 kristaps 37: .Fl u Ar dir
38: .Op Ar
1.15 schwarze 39: .Nm
40: .Fl t Ar
1.1 schwarze 41: .Sh DESCRIPTION
42: The
43: .Nm
44: utility extracts keywords from
45: .Ux
1.18 kristaps 46: manuals and indexes them in a database for fast retrieval by
1.17 schwarze 47: .Xr apropos 1 ,
48: .Xr whatis 1 ,
49: and
1.21 ! schwarze 50: .Xr man 1 Ns 's
! 51: .Fl k
! 52: option.
1.7 schwarze 53: .Pp
1.8 schwarze 54: By default,
55: .Nm
1.18 kristaps 56: creates a database in each
1.8 schwarze 57: .Ar dir
58: using the files
59: .Sm off
60: .Sy man Ar section Li /
61: .Op Ar arch Li /
62: .Ar title . section
63: .Sm on
64: and
65: .Sm off
66: .Sy cat Ar section Li /
67: .Op Ar arch Li /
68: .Ar title . Sy 0
69: .Sm on
1.18 kristaps 70: in that directory.
71: Existing databases are replaced.
1.8 schwarze 72: If
73: .Ar dir
74: is not provided,
75: .Nm
76: uses the default paths stipulated by
1.18 kristaps 77: .Xr manpath 1 ,
78: or
79: .Xr man.conf 5 .
1.8 schwarze 80: .Pp
1.1 schwarze 81: The arguments are as follows:
1.12 schwarze 82: .Bl -tag -width "-C file"
1.7 schwarze 83: .It Fl a
84: Use all directories and files found below
85: .Ar dir ... .
1.12 schwarze 86: .It Fl C Ar file
87: Specify an alternative configuration
88: .Ar file
89: in
90: .Xr man.conf 5
91: format.
1.3 kristaps 92: .It Fl d Ar dir
1.5 kristaps 93: Merge (remove and re-add)
1.3 kristaps 94: .Ar
1.8 schwarze 95: to the database in
1.18 kristaps 96: .Ar dir .
97: .It Fl n
98: Do not create or modify any database;
99: scan and parse only.
1.15 schwarze 100: .It Fl t Ar
101: Check the given
102: .Ar files
103: for potential problems.
104: Implies
1.18 kristaps 105: .Fl a ,
106: .Fl n ,
1.15 schwarze 107: and
108: .Fl W .
109: All diagnostic messages are printed to the standard output;
110: the standard error output is not used.
1.3 kristaps 111: .It Fl u Ar dir
1.5 kristaps 112: Remove
1.3 kristaps 113: .Ar
1.8 schwarze 114: from the database in
1.18 kristaps 115: .Ar dir .
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: .Sh FILES
127: .Bl -tag -width Ds
1.20 schwarze 128: .It Pa mandoc.db
1.18 kristaps 129: A database of manpages relative to the directory of the file.
130: This file is portable across architectures and systems, so long as the
131: manpage hierarchy it indexes does not change.
1.21 ! schwarze 132: .It Pa /etc/man.conf
! 133: The default
! 134: .Xr man 1
! 135: configuration file.
1.1 schwarze 136: .El
137: .Sh EXIT STATUS
1.21 ! schwarze 138: The
! 139: .Nm
! 140: utility exits with one of the following values:
! 141: .Pp
! 142: .Bl -tag -width Ds -compact
! 143: .It 0
! 144: No errors occurred.
! 145: .It 5
! 146: Invalid command line arguments were specified.
! 147: No input files have been read.
! 148: .It 6
! 149: An operating system error occurred, for example memory exhaustion or an
! 150: error accessing input files.
! 151: Such errors cause
! 152: .Nm
! 153: to exit at once, possibly in the middle of parsing or formatting a file.
! 154: The output databases are corrupt and should be removed.
! 155: .El
1.1 schwarze 156: .Sh SEE ALSO
1.12 schwarze 157: .Xr apropos 1 ,
1.6 kristaps 158: .Xr man 1 ,
1.12 schwarze 159: .Xr whatis 1 ,
160: .Xr man.conf 5
1.20 schwarze 161: .Sh HISTORY
162: A
163: .Nm makewhatis
164: utility first appeared in
165: .Bx 2 .
166: It was rewritten in
167: .Xr perl 1
168: for
169: .Ox 2.7
170: and in C for
171: .Ox 5.1 .
172: .Pp
173: The
174: .Ar dir
175: argument first appeared in
176: .Nx 1.0 ;
177: the options
178: .Fl dtu
179: in
180: .Ox 2.7 ;
181: and the options
182: .Fl aCvW
183: in
184: .Ox 5.1 .
1.1 schwarze 185: .Sh AUTHORS
1.20 schwarze 186: .An -nosplit
187: .An Bill Joy
188: wrote the original
189: .Bx
190: .Nm makewhatis
191: in February 1979,
192: .An Marc Espie
193: started the Perl version in 2000,
194: and the current version of
1.1 schwarze 195: .Nm
1.20 schwarze 196: was written by
197: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1.18 kristaps 198: and
1.19 schwarze 199: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
CVSweb