Debian Codegraph @

upstream/debian-unstable/man1/xman.1

raw
1 .\" t
2 .\"
3 .TH XMAN 1 "xman 1.1.6" "X Version 11"
4 .SH NAME
5 xman \- Manual page display program for the X Window System
6 .SH SYNOPSIS
7 .B xman
8 [
9 .I \-options
10 \&.\|.\|. ]
11 .SH DESCRIPTION
12 .I Xman
13 is a manual page browser. The default size of the initial \fIxman\fP
14 window is small so that you can leave it running throughout your entire login
15 session. In the initial window there are three options:
16 \fIHelp\fP will pop up a window with on-line help, \fIQuit\fP will
17 exit, and \fIManual Page\fP will pop up a window with a manual page
18 browser in it.
19 Typing Control-S will pop up a window prompting for a specific manual
20 page to display.
21 You may display more than one manual page browser window at a time
22 from a single execution of \fIxman\fP.
23 .PP
24 For further information on using \fIxman\fP, please read the on-line
25 help information. Most of this manual will discuss
26 customization of \fIxman\fP.
27 .SH "OPTIONS"
28 .PP
29 Xman supports all standard Toolkit command line arguments (see
30 \fIX\fP(7)). The following additional arguments are supported.
31 .sp
32 .IP "\fB\-helpfile\fP \fIfilename\fP"
33 Specifies a helpfile to use other than the default.
34 .IP \fB\-bothshown\fP
35 Allows both the manual page and manual directory to be on the screen at
36 the same time.
37 .IP \fB\-notopbox\fP
38 Starts without the Top Menu with the three buttons in it.
39 .IP "\fB\-geometry\fP \fIWxH+X+Y\fP"
40 Sets the size and location of the Top Menu with the three buttons in it.
41 .IP "\fB\-pagesize\fP \fIWxH+X+Y\fP"
42 Sets the size and location of all the Manual Pages.
43 .IP "\fB\-help\fP"
44 Print a usage message and exit.
45 .IP "\fB\-version\fP"
46 Print the program version and exit.
47 .SH "CUSTOMIZING XMAN"
48 .PP
49 .I Xman
50 allows customization of both the directories to be searched for manual pages,
51 and the name that each directory will map to in the \fISections\fP
52 menu. Xman determines which directories it will
53 search by reading the \fIMANPATH\fP environment variable. If no
54 \fIMANPATH\fP is found then the directory is /usr/man is searched on
55 POSIX systems. This environment
56 is expected to be a colon-separated list of directories for xman to search.
57 .sp
58 .nf
59 setenv MANPATH /mit/kit/man:/usr/man
60 .fi
61 .PP
62 By default,
63 .I xman
64 will search each of the following directories (in each of the directories
65 specified in the users MANPATH) for manual pages. If manual pages exist
66 in that directory then they are added to list of manual pages for
67 the corresponding menu item.
68 A menu item is only displayed for those sections that actually contain
69 manual pages.
70
71 .TS
72 l l.
73 Directory Section Name
74 - -
75 man1 (1) User Commands
76 man2 (2) System Calls
77 man3 (3) Subroutines
78 man4 (4) Devices
79 man5 (5) File Formats
80 man6 (6) Games
81 man7 (7) Miscellaneous
82 man8 (8) Sys. Administration
83 manl (l) Local
84 mann (n) New
85 mano (o) Old
86 .TE
87
88 For instance, a user has three directories in her manual path and each
89 contain a directory called \fIman3\fP. All these manual pages will appear
90 alphabetically sorted when the user selects the menu item called
91 \fI(3) Subroutines\fP. If there is no directory called
92 \fImano\fP in any of the directories in her MANPATH, or there are no manual
93 pages in any of the directories called \fImano\fP then no menu item will be
94 displayed for the section called \fI(o) Old\fP.
95 .SH "BSD AND LINUX SYSTEMS"
96 .PP
97 In newer BSD and Linux systems, \fIXman\fP will search for a file named
98 \fI/etc/man.conf\fP which will contain the list of directories containing
99 manual pages. See \fIman.conf\fP(5) for a complete description of the file
100 format.
101 .SH "THE MANDESC FILE"
102 .PP
103 By using the \fImandesc\fP file a user or system manager is able to
104 more closely control which manual pages will appear in each of the sections
105 represented by menu items in the \fISections\fP menu. This
106 functionality is only available on a section by section basis, and individual
107 manual pages may not be handled in this manner.
108 (Although generous use of
109 symbolic links \(em see \fIln\fP(1) \(em will allow
110 almost any configuration you can imagine.)
111 .PP
112 The format of the mandesc file is a character followed by a label. The
113 character determines which of the sections will be added under this label.
114 For instance suppose that you would like to create an extra menu item that
115 contains all programmer subroutines. This label should contain all manual
116 pages in both sections two and three. The \fImandesc\fP file
117 would look like this:
118 .nf
119
120 2Programmer Subroutines
121 3Programmer Subroutines
122
123 .fi
124 This will add a menu item to the \fISections\fP menu that would
125 bring up a listing of all manual pages in sections two and three of
126 the Programmers Manual. Since the label names are \fIexactly\fP the
127 same they will be added to the same section. Note, however, that the
128 original sections still exist.
129 .PP
130 If you want to completely ignore the default sections in a manual directory
131 then add the line:
132 .nf
133
134 no default sections
135
136 .fi
137 anywhere in your mandesc file. This keeps xman from searching
138 the default manual sections \fIIn that directory only\fP. As an example,
139 suppose you want to do the same thing as above, but you don't think that
140 it is useful to have the \fISystem Calls\fP or \fISubroutines\fP sections
141 any longer. You would need to duplicate the default entries, as well as
142 adding your new one.
143 .nf
144
145 no default sections
146 1(1) User Commands
147 2Programmer Subroutines
148 3Programmer Subroutines
149 4(4) Devices
150 5(5) File Formats
151 6(6) Games
152 7(7) Miscellaneous
153 8(8) Sys. Administration
154 l(l) Local
155 n(n) New
156 o(o) Old
157
158 .fi
159 Xman will read any section that is of the form \fIman<character>\fP, where
160 <character> is an upper or lower case letter (they are treated distinctly) or
161 a numeral (0-9). Be warned, however, that man(1) and
162 catman(8) will not search directories that are non-standard.
163 .SH WIDGETS
164 In order to specify resources, it is useful to know the hierarchy of
165 the widgets which compose \fIxman\fR. In the notation below,
166 indentation indicates hierarchical structure. The widget class name
167 is given first, followed by the widget instance name.
168 .sp
169 .nf
170 .ft CW
171 Xman xman \fI(This widget is never used)\fP
172 TopLevelShell topBox
173 Form form
174 Label topLabel
175 Command helpButton
176 Command quitButton
177 Command manpageButton
178 TransientShell search
179 DialogWidgetClass dialog
180 Label label
181 Text value
182 Command manualPage
183 Command apropos
184 Command cancel
185 TransientShell pleaseStandBy
186 Label label
187 TopLevelShell manualBrowser
188 Paned Manpage_Vpane
189 Paned horizPane
190 MenuButton options
191 MenuButton sections
192 Label manualBrowser
193 Viewport directory
194 List directory
195 List directory
196 .
197 . (one for each section,
198 . created on the fly)
199 .
200 ScrollByLine manualPage
201 SimpleMenu optionMenu
202 SmeBSB displayDirectory
203 SmeBSB displayManualPage
204 SmeBSB help
205 SmeBSB search
206 SmeBSB showBothScreens
207 SmeBSB removeThisManpage
208 SmeBSB openNewManpage
209 SmeBSB showVersion
210 SmeBSB quit
211 SimpleMenu sectionMenu
212 SmeBSB <name of section>
213 .
214 . (one for each section)
215 .
216 TransientShell search
217 DialogWidgetClass dialog
218 Label label
219 Text value
220 Command manualPage
221 Command apropos
222 Command cancel
223 TransientShell pleaseStandBy
224 Label label
225 TransientShell likeToSave
226 Dialog dialog
227 Label label
228 Text value
229 Command yes
230 Command no
231 TopLevelShell help
232 Paned Manpage_Vpane
233 Paned horizPane
234 MenuButton options
235 MenuButton sections
236 Label manualBrowser
237 ScrollByLine manualPage
238 SimpleMenu optionMenu
239 SmeBSB displayDirectory
240 SmeBSB displayManualPage
241 SmeBSB help
242 SmeBSB search
243 SmeBSB showBothScreens
244 SmeBSB removeThisManpage
245 SmeBSB openNewManpage
246 SmeBSB showVersion
247 SmeBSB quit
248
249 .ft
250 .fi
251 .SH "APPLICATION RESOURCES"
252 \fIxman\fP has the following application-specific resources which allow
253 customizations unique to \fIxman\fP.
254 .PP
255 .TP 18
256 \fBmanualFontNormal\fP (Class \fBFont\fP)
257 The font to use for normal text in the manual pages.
258 .TP 18
259 \fBmanualFontBold\fP (Class \fBFont\fP)
260 The font to use for bold text in the manual pages.
261 .TP 18
262 \fBmanualFontItalic\fP (Class \fBFont\fP)
263 The font to use for italic text in the manual pages.
264 .TP 18
265 \fBdirectoryFontNormal\fP (Class \fBFont\fP)
266 The font to use for the directory text.
267 .TP 18
268 \fBbothShown\fP (Class \fBBoolean\fP)
269 Either `true' or `false,' specifies whether or not you want both the
270 directory and the manual page shown at start up.
271 .TP 18
272 \fBdirectoryHeight\fP (Class \fBDirectoryHeight\fP)
273 The height in pixels of the directory, when the directory and the manual page
274 are shown simultaneously.
275 .TP 18
276 \fBtopCursor\fP (Class \fBCursor\fP)
277 The cursor to use in the top box.
278 .TP 18
279 \fBhelpCursor\fP (Class \fBCursor\fP)
280 The cursor to use in the help window.
281 .TP 18
282 \fBmanpageCursor\fP (Class \fBCursor\fP)
283 The cursor to use in the manual page window.
284 .TP 18
285 \fBsearchEntryCursor\fP (Class \fBCursor\fP)
286 The cursor to use in the search entry text widget.
287 .TP 18
288 \fBpointerColor\fP (Class \fBForeground\fP)
289 This is the color of all the cursors (pointers) specified above. The
290 name was chosen to be compatible with xterm.
291 .TP 18
292 \fBhelpFile\fP (Class \fBFile\fP)
293 Use this rather than the system default helpfile.
294 .TP 18
295 \fBtopBox\fP (Class \fBBoolean\fP)
296 Either `true' or `false,' determines whether the top box (containing
297 the help, quit and manual page buttons) or a manual page is put on the screen
298 at start-up. The default is true.
299 .TP 18
300 \fBverticalList\fP (Class \fBBoolean\fP)
301 Either `true' or `false,' determines whether the directory listing is
302 vertically or horizontally organized. The default is horizontal (false).
303 .SH "GLOBAL ACTIONS"
304 \fIXman\fP defines all user interaction through global actions. This allows
305 the user to modify the translation table of any widget, and bind any event
306 to the new user action. The list of actions supported by \fIxman\fP are:
307 .TP 1.5i
308 .B GotoPage(\fIpage\fB)
309 When used in a manual page display window this will allow the user to
310 move between a directory and manual page display. The \fIpage\fP argument can
311 be either \fBDirectory\fP or \fBManualPage\fP.
312 .TP 1.5i
313 .B Quit()
314 This action may be used anywhere, and will exit xman.
315 .TP 1.5i
316 .B Search(\fItype\fB, \fIaction\fB)
317 Only useful when used in a search popup, this action will cause the search
318 widget to perform the named search type on the string in the search popup's
319 value widget. This action will also pop down the search widget. The
320 \fItype\fP argument can be either \fBApropos\fP, \fBManpage\fP or
321 \fBCancel\fP. If an \fIaction\fP of \fBOpen\fP is specified then xman
322 will open a new manual page to display the results of the search, otherwise
323 xman will attempt to display the results in the parent of the search popup.
324 .TP 1.5i
325 .B PopupHelp()
326 This action may be used anywhere, and will popup the help widget.
327 .TP 1.5i
328 .B PopupSearch()
329 This action may be used anywhere except in a help window. It will cause
330 the search popup to become active and visible on the screen, allowing
331 the user search for a manual page.
332 .TP 1.5i
333 .B CreateNewManpage()
334 This action may be used anywhere, and will create a new manual page
335 display window.
336 .TP 1.5i
337 .B RemoveThisManpage()
338 This action may be used in any manual page or help display window. When
339 called it will remove the window, and clean up all resources
340 associated with it.
341 .TP 1.5i
342 .B SaveFormattedPage(\fIaction\fP)
343 This action can only be used in the \fBlikeToSave\fP popup widget, and
344 tells xman whether to \fBSave\fP or \fBCancel\fP a save of the
345 manual page that has just been formatted.
346 .TP 1.5i
347 .B ShowVersion()
348 This action may be called from any manual page or help display window, and
349 will cause the informational display line to show the current version
350 of xman.
351 .SH FILES
352 .IP "\fI<manpath directory>\fP/man<\fIcharacter\fP>" 2.5i
353 .IP "\fI<manpath directory>\fP/cat<\fIcharacter\fP>"
354 .IP "\fI<manpath directory>\fP/mandesc"
355 .IP /etc/X11/app-defaults/Xman
356 specifies required resources.
357 .IP /tmp
358 .I Xman
359 creates temporary files in /tmp for all unformatted man pages and all apropos
360 searches.
361 .SH "SEE ALSO"
362 .IR X (7),
363 .IR man (1),
364 .IR apropos (1),
365 .IR catman (8),
366 .I "Athena Widget Set"
367 .SH ENVIRONMENT
368 .TP 1.5i
369 .B DISPLAY
370 the default host and display to use.
371 .TP 1.5i
372 .B MANPATH
373 the search path for manual pages. Directories are separated by
374 colons (e.g. /usr/man:/mit/kit/man:/foo/bar/man).
375 .TP 1.5i
376 .B XENVIRONMENT
377 to get the name of a resource file that overrides the global resources
378 stored in the RESOURCE_MANAGER property.
379 .TP 1.5i
380 .B XAPPLRESDIR
381 A string that will have ``Xman'' appended to it. This string will be
382 the full path name of a user app-defaults file to be merged into the
383 resource database after the system app-defaults file, and before
384 the resources that are attached to the display.
385 .SH AUTHORS
386 Chris Peterson, MIT X Consortium from the V10 version written by Barry
387 Shein formerly of Boston University.
388 Bug fixes and Linux support by Carlos A M dos Santos, for The XFree86 Project.