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