]> git.cameronkatri.com Git - mandoc.git/blob - whatis.1
Flip apropos to use mansearch instead of apropos_db.
[mandoc.git] / whatis.1
1 .\" $Id: whatis.1,v 1.9 2012/03/25 00:48:47 kristaps Exp $
2 .\"
3 .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
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 .\"
17 .Dd $Mdocdate: March 25 2012 $
18 .Dt WHATIS 1
19 .Os
20 .Sh NAME
21 .Nm whatis
22 .Nd search for manual pages by page names
23 .Sh SYNOPSIS
24 .Nm
25 .Op Fl C Ar file
26 .Op Fl M Ar manpath
27 .Op Fl m Ar manpath
28 .Op Fl S Ar arch
29 .Op Fl s Ar section
30 .Ar name ...
31 .Sh DESCRIPTION
32 The
33 .Nm
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
40 By default,
41 .Nm
42 searches for
43 .Xr mandocdb 8
44 databases in the default paths stipulated by
45 .Xr man 1 .
46 If standard output is a TTY, a result may be selected from a list and
47 its manual displayed with the pager.
48 .Pp
49 The options are as follows:
50 .Bl -tag -width Ds
51 .It Fl C Ar file
52 Specify an alternative configuration
53 .Ar file
54 in
55 .Xr man.conf 5
56 format.
57 .It Fl M Ar manpath
58 Use the colon-separated
59 .Ar manpath
60 instead of the default list of paths searched for
61 .Xr mandocdb 8
62 databases.
63 Invalid paths, or paths without manual databases, are ignored.
64 .It Fl m Ar manpath
65 Prepend the colon-separated
66 .Ar manpath
67 to the list of paths searched for
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
96 If on a TTY, results are prefixed with a numeric identifier.
97 .Pp
98 .D1 [index] title(cat) \- description
99 .Pp
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 .
111 .Pp
112 .Nm
113 is identical to running
114 .Xr apropos 1
115 as follows:
116 .Pp
117 .Dl $ apropos -- -i 'Nm~[[:<:]]term[[:>:]]'
118 .Sh ENVIRONMENT
119 .Bl -tag -width Ds
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 .
128 .It Ev MANPATH
129 Colon-separated paths modifying the default list of paths searched for
130 manual databases.
131 Invalid paths, or paths without manual databases, are ignored.
132 Overridden by
133 .Fl M .
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.
145 .El
146 .Sh FILES
147 .Bl -tag -width "/etc/man.conf" -compact
148 .It Pa whatis.db
149 name of the
150 .Xr mandocdb 8
151 keyword database
152 .It Pa whatis.index
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
161 .Sh EXIT STATUS
162 .Ex -std
163 .Sh SEE ALSO
164 .Xr apropos 1 ,
165 .Xr man 1 ,
166 .Xr man.conf 5 ,
167 .Xr mandocdb 8
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 .
177 .Sh AUTHORS
178 .An -nosplit
179 .An Bill Joy
180 wrote the original
181 .Bx
182 .Nm
183 in 1979.
184 The current version was written by
185 .An Kristaps Dzonsons ,
186 .Mt kristaps@bsd.lv .