Annotation of mandoc/whatis.1, Revision 1.9
1.9 ! kristaps 1: .\" $Id: whatis.1,v 1.8 2012/03/24 01:54:43 kristaps Exp $
1.1 kristaps 2: .\"
1.8 kristaps 3: .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
1.1 kristaps 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.9 ! kristaps 17: .Dd $Mdocdate: March 24 2012 $
1.1 kristaps 18: .Dt WHATIS 1
19: .Os
20: .Sh NAME
21: .Nm whatis
1.4 schwarze 22: .Nd search for manual pages by page names
1.1 kristaps 23: .Sh SYNOPSIS
24: .Nm
1.4 schwarze 25: .Op Fl C Ar file
1.1 kristaps 26: .Op Fl M Ar manpath
27: .Op Fl m Ar manpath
28: .Op Fl S Ar arch
29: .Op Fl s Ar section
1.4 schwarze 30: .Ar name ...
1.1 kristaps 31: .Sh DESCRIPTION
32: The
33: .Nm
1.4 schwarze 34: utility searches databases generated by
35: .Xr mandocdb 8
36: for manuals containing the word
37: .Ar name
38: in their page name, ignoring case.
39: .Pp
1.7 kristaps 40: By default,
41: .Nm
42: searches for
43: .Xr mandocdb 8
44: databases in the default paths stipulated by
45: .Xr man 1 .
1.8 kristaps 46: If standard output is a TTY, a result may be selected from a list and
47: its manual displayed with the pager.
1.7 kristaps 48: .Pp
1.4 schwarze 49: The options are as follows:
1.1 kristaps 50: .Bl -tag -width Ds
1.4 schwarze 51: .It Fl C Ar file
52: Specify an alternative configuration
53: .Ar file
54: in
55: .Xr man.conf 5
56: format.
1.1 kristaps 57: .It Fl M Ar manpath
1.4 schwarze 58: Use the colon-separated
59: .Ar manpath
60: instead of the default list of paths searched for
1.1 kristaps 61: .Xr mandocdb 8
62: databases.
63: Invalid paths, or paths without manual databases, are ignored.
64: .It Fl m Ar manpath
1.4 schwarze 65: Prepend the colon-separated
66: .Ar manpath
67: to the list of paths searched for
1.1 kristaps 68: .Xr mandocdb 8
69: databases.
70: Invalid paths, or paths without manual databases, are ignored.
71: .It Fl S Ar arch
72: Search only for a particular architecture.
73: .It Fl s Ar cat
74: Search only for a manual section.
75: See
76: .Xr man 1
77: for a listing of manual sections.
78: .El
79: .Pp
80: Results are sorted by manual title, with output formatted as
81: .Pp
82: .D1 title(sec) \- description
83: .Pp
84: Where
85: .Qq title
86: is the manual's title (note multiple manual names may exist for one
87: title),
88: .Qq sec
89: is the manual section, and
90: .Qq description
91: is the manual's short description.
92: If an architecture is specified for the manual, it is displayed as
93: .Pp
94: .D1 title(cat/arch) \- description
95: .Pp
1.8 kristaps 96: If on a TTY, results are prefixed with a numeric identifier.
1.1 kristaps 97: .Pp
1.8 kristaps 98: .D1 [index] title(cat) \- description
1.1 kristaps 99: .Pp
1.8 kristaps 100: One may choose a manual be entering the index at the prompt.
101: Valid choices are displayed using
102: .Ev MANPAGER ,
103: or failing that ,
104: .Ev PAGER
105: or just
106: .Xr more 1 .
107: Source pages are formatted with
108: .Xr mandoc 1 ;
109: preformatted pages with
110: .Xr cat 1 .
1.1 kristaps 111: .Pp
112: .Nm
113: is identical to running
114: .Xr apropos 1
115: as follows:
116: .Pp
1.2 schwarze 117: .Dl $ apropos -- -i 'Nm~[[:<:]]term[[:>:]]'
1.1 kristaps 118: .Sh ENVIRONMENT
119: .Bl -tag -width Ds
1.8 kristaps 120: .It Ev MANPAGER
121: Default pager for manuals.
122: If this is unset, falls back to
123: .Ev Pager .
124: .It Ev PAGER
125: The second choice for a manual pager.
126: If this is unset, use
127: .Xr more 1 .
1.1 kristaps 128: .It Ev MANPATH
1.5 kristaps 129: Colon-separated paths modifying the default list of paths searched for
1.1 kristaps 130: manual databases.
131: Invalid paths, or paths without manual databases, are ignored.
132: Overridden by
133: .Fl M .
1.5 kristaps 134: If
135: .Ev MANPATH
136: begins with a
137: .Sq \&: ,
138: it is appended to the default list;
139: else if it ends with
140: .Sq \&: ,
141: it is prepended to the default list; else if it contains
142: .Sq \&:: ,
143: the default list is inserted between the colons.
144: If none of these conditions are met, it overrides the default list.
1.1 kristaps 145: .El
1.4 schwarze 146: .Sh FILES
147: .Bl -tag -width "/etc/man.conf" -compact
1.6 schwarze 148: .It Pa whatis.db
1.4 schwarze 149: name of the
150: .Xr mandocdb 8
151: keyword database
1.6 schwarze 152: .It Pa whatis.index
1.4 schwarze 153: name of the
154: .Xr mandocdb 8
155: filename database
156: .It Pa /etc/man.conf
157: default
158: .Xr man 1
159: configuration file
160: .El
1.1 kristaps 161: .Sh EXIT STATUS
162: .Ex -std
163: .Sh SEE ALSO
164: .Xr apropos 1 ,
165: .Xr man 1 ,
1.4 schwarze 166: .Xr man.conf 5 ,
1.1 kristaps 167: .Xr mandocdb 8
1.4 schwarze 168: .Sh HISTORY
169: The
170: .Nm
171: utility first appeared in
172: .Bx 2 .
173: It was rewritten from scratch as part of the
174: .Xr mandocdb 8
175: project for
176: .Ox 5.1 .
1.1 kristaps 177: .Sh AUTHORS
1.4 schwarze 178: .An -nosplit
179: .An Bill Joy
180: wrote the original
181: .Bx
1.1 kristaps 182: .Nm
1.4 schwarze 183: in 1979.
184: The current version was written by
1.1 kristaps 185: .An Kristaps Dzonsons ,
186: .Mt kristaps@bsd.lv .
CVSweb