.TH xman "" "" "X Application"
.PC "Select and display manual pages graphically"
\fBxman [\fIoptions\^\fB...\^\fB]\fR
.PP
.HS
.SH Options:
.IC "\fB\-bd \fIcolor\fR"
Set the color of the border to \fIcolor\fR
.IC "\fB\-bg \fIcolor\fR"
Set the color of the background to \fIcolor\fR
.IC \fB\-bothshown\fR
Let the manual page and manual directory both be on the screen
simultaneously
.IC "\fB\-bw \fIpixels\fR"
Set the width of the border to \fIpixels\fR
.IC "\fB\-display \fIhost\^\fB[:\fIserver\^\fB][.\fIscreen\^\fB]\fR"
Display the client's window on screen number \fIscreen\fR
of \fIserver\fR on host system \fIhost\fR
.IC "\fB\-fg \fIcolor\fR"
Set the color of the foreground to \fIcolor\fR
.IC "\fB\-fn \fIfont\fR"
Use \fIfont\fR in the display
.IC "\fB\-geometry\fP \fIWxH+X+Y\fP"
Set the size and location of the three-button control window.
The term ``geometry'' means the dimensions of the window and its location
on the screen.
.I geometry
has the form \fIwidth\(muheight\(+-xoffset\(+-yoffset\fR.
.IC "\fB\-helpfile \fIfilename\fR"
Use
.I helpfile
instead of the default help file
.BR /usr/X11/lib/xman.help .
.IC \fB\-notopbox\fP
Do not start by displaying the three-button control window.
.IC "\fB\-pagesize\fP \fIWxH+X+Y\fR"
Set the size and location of the browser window.
.IC \fB\-rv\fR
Simulate reverse video by exchanging the foreground and background colors
.IC "\fB\-xrm \fIresourcestring\fR"
Use \fIresourcestring\fR to define a resource
.HE
.B xman
is a tool by which you can browse through the manual pages on your system,
and interactively select and display manual pages.
.PP
The following illustrates how
.B xman
appears on your screen:
.PH 1 1 /v/PostScript/manual/xman.eps
The rest of this page refers to the above illustration.
.PP
When
.B xman
first comes up, it displays the small window that appears in the upper right
corner of the screen shown above.
As you can see, this window has the following three buttons on it:
.IP \fK(Help)\fR
This button invokes
.BR xman 's
internal function
.BR PopupHelp() ,
which pops up a window that describes how to use
.BR xman .
.IP \fK(Quit)\fR
Exit from
.B xman
altogether.
.IP \fK(Manual_Page)\fR
This button opens a browser window.
.PP
The control window recognizes the following control-key sequences:
.IP \fB<ctrl-C>\fR
Quit
.BR xman .
This is the same as clicking on the
.K Quit
button.
.IP \fB<ctrl-N>\fR
Invoke
.BR xman 's
internal function
.BR CreateNewManage() .
Under \*(CO, this is the same as invoking the browser window.
.IP \fB<ctrl-S>\fR
.B xman
invokes its function
.BR PopupSearch() ,
which pops up a window that prompts for a specific manual page to display.
(This window is not illustrated above.)
Note that unlike the \*(CO command
.BR man ,
you must enter the name of the file that you wish to display,
.I not
the name of the entry as it appears in the Lexicon.
In most cases (e.g., \fBprintf\fR)
the name of the entry and the name of the file are the same; however, in
others (e.g., \fB#ifdef\fR) they are not.
.II /usr/man/man.index
.II man.index
If you are unsure of how a manual entry corresponds to a file name,
browse through file
.BR /usr/man/man.index .
.PP
When you click the button
.K Manual_Page
in
.BR xman 's
control window,
.B xman
displays a browser window.
This window is displayed in the middle of the screen shown above;
it has the title
.IR "Manual Page" .
.PP
As you can see, the browser has a title bar across the top.
This bar has two buttons, which are labelled, respectively,
.K Options
and
.KR Sections .
To the right of the buttons is a strip where
.B xman
display information about its current activity.
To the left of the window is a slider, which you can manipulate in the
usual fashion.
.PP
When the browser window first opens, the body of the window (the area
below the bar) displays
.BR xman 's
help information.
.PP
When you click and drag the button
.KR Sections ,
.B xman
displays a window that shows every directory under
.BR /usr/man .
To view the contents of a given directory, slide the mouse cursor down until
the directory you want is in reverse video; then release the mouse button.
.B xman
then displays in the body of its window the contents of the directory
you have selected.
The above illustration displays the contents of file
.BR /usr/man/COHERENT.2 .
Once you have displayed the contents of a directory, you can select a
manual page simply by moving the mouse cursor to its name and clicking it.
.PP
The button
.K Options
lets you manipulate the manual page you have selected, and also lets you
modify the behavior of
.BR xman .
The above illustration shows the menu that
.B xman
displays when you click
.KR Options .
It contains the following entries:
.IP \fK(Display_Directory)\fR
This displays the contents of the sub-directory under
.B /usr/man
that comes first in alphabetical order.
In most \*(CO installations, this will be directory
.BR /usr/man/COHERENT.1 .
.IP \fK(Display_Manual_Page)\fR
This displays in the body of the browser window
the manual that you have selected.
If you have not yet selected a manual page, it redisplays
.BR xman 's
help page.
.IP \fK(Help)\fR
This displays (or redisplays)
.BR xman 's
help information in the body of the browser window.
.IP \fK(Search)\fR
Search for information within the manual.
When you make this selection, a window enters that has a field for
entering data, plus three buttons.
Type the string for which you want to search, then press one of the
buttons, as follows:
.RS
.IP \fK(Manual_Page)\fR
Search
.B /usr/man
and its subdirectories for any files whose names match the string you
typed.
If
.B xman
finds any, it displays them in the body of the browser window.
.IP \fK(Apropos)\fR
.B xman
invokes the \*(CO command
.B apropos
with the string that you entered.
It then displays the output of
.B apropos
within the body of the browser window.
.IP \fK(Cancel)\fR
Cancel this request.
.RE
.IP \fK(Show_Both_Screens)\fR
Normally,
.B xman
displays the file that you select within the body of the browser window.
However, clicking this button tells
.B xman
to open another browser window and display within it
the manual page you have selected.
This lets you display multiple manual pages simultaneously.
.IP \fK(Remove_This_Manpage)\fR
This removes the manual page you have selected.
Note that
.B xman
can execute this command only if you have appropriate permissions
within directory
.BR /usr/man .
.IP \fK(Open_New_Manpage)\fR
Under some implementations of X, this lets you reformat a manual page.
Since \*(CO ships all of its manual pages already formatted, this selection
simply re-displays
.BR xman 's
help screen.
.IP \fK(Show_Version)\fR
This shows the version of
.B xman
that you are using.
.B xman
displays this information in the strip at the top of the browser window.
.IP \fK(Quit)\fR
Close this window.
.PP
To summarize, you should do the following to display a manual page:
.IP \(bu 0.3i
Click
.K Manual_Page
in
.BR xman 's
control window.
This opens the browser window
.IP \(bu
Click
.K Select
on the browser window.
Select the directory whose contents you want to see.
.IP \(bu
Use the scroll bar to scroll through the contents of the browser window.
Click on the name of the file that interests you.
.IP \(bu
Press the
.K Options
button at the top of the browser window.
Select
.K Display_Manual_Page
from its menu.
.B xman
displays the manual page you have selected.
.SH "Command-line Options"
.B xman
recognizes the following command-line options:
.IP "\fB\-bd \fIcolor\fR"
Set the color of the border to
.IR color .
.IP "\fB\-bg \fIcolor\fR"
Set the color of the background to
.IR color .
.IP \fB\-bothshown\fR
Let the manual page and manual directory both be on the screen
simultaneously.
.IP "\fB\-bw \fIpixels\fR"
Set the width of the border to
.IR pixels .
.IP "\fB\-display \fIhost\^\fB[:\fIserver\^\fB][.\fIscreen\^\fB]\fR"
Display the client's window on screen number
.I screen
of
.I server
on host system
.IR host .
.IP "\fB\-fg \fIcolor\fR"
Set the color of the foreground to
.IR color .
.IP "\fB\-fn \fIfont\fR"
Use
.I font
in the display.
.IP "\fB\-geometry\fP \fIWxH+X+Y\fP"
Set the size and location of the three-button control window.
The term ``geometry'' means the dimensions of the window and its location
on the screen.
.I geometry
has the form \fIwidth\(muheight\(+-xoffset\(+-yoffset\fR.
.IP "\fB\-helpfile \fIfilename\fR"
.II "xman.help"
Use
.I helpfile
instead of the default help file
.BR /usr/X11/lib/xman.help .
.IP \fB\-notopbox\fP
Do not start by displaying the three-button control window.
.IP "\fB\-pagesize\fP \fIWxH+X+Y\fR"
Set the size and location of the browser window.
.IP \fB\-rv\fR
Simulate reverse video by exchanging the foreground and background colors.
.IP "\fB\-xrm \fIresourcestring\fR"
Use
.I resourcestring
to define a resource.
.SH Widgets
If you wish to specify resources, you will find it useful
to know the hierarchy of the widgets that comprise
.BR xman .
In the notation below, indentation indicates hierarchy.
The widget's class name is given first, followed by its instance name.
.nf
.sp \n(pDu
	TopLevelShell  topbox
		Form  form
			Label  topLabel
			Command  helpButton
			Command  quitButton
			Command  manpageButton
		TransientShell  search
			DialogWidgetClass  dialog
				Label  label
				Text  value
				Command  manualPage
				Command  apropos
				Command  cancel
		TransientShell  pleaseStandBy
			Label  label
	TopLevelShell  manualBrowser
		Paned  Manpage_Vpane
			Paned  horizPane
				MenuButton  options
				MenuButton  sections
				Label  manualBrowser
			Viewport  directory
				List  directory	
				List  directory	
				.
				. (one for each section, 
				.  created on the fly)
				.
			ScrollByLine  manualPage
		SimpleMenu  optionMenu
			SmeBSB  displayDirectory
			SmeBSB  displayManualPage
			SmeBSB  help
			SmeBSB  search
			SmeBSB  showBothScreens
			SmeBSB  removeThisManpage
			SmeBSB  openNewManpage
			SmeBSB  showVersion
			SmeBSB  quit
		SimpleMenu  sectionMenu
			SmeBSB  <name of section>
			 	.
				. (one for each section)
				.
		TransientShell  search
			DialogWidgetClass  dialog
				Label  label
				Text  value
				Command  manualPage
				Command  apropos
				Command  cancel
		TransientShell  pleaseStandBy
			Label  label
		TransientShell  likeToSave
			Dialog  dialog
				Label  label
				Text  value
				Command  yes
				Command  no
	TopLevelShell  help
		Paned  Manpage_Vpane
			Paned  horizPane
				MenuButton  options
				MenuButton  sections
				Label  manualBrowser
			ScrollByLine  manualPage
		SimpleMenu  optionMenu
			SmeBSB  displayDirectory
			SmeBSB  displayManualPage
			SmeBSB  help
			SmeBSB  search
			SmeBSB  showBothScreens
			SmeBSB  removeThisManpage
			SmeBSB  openNewManpage
			SmeBSB  showVersion
			SmeBSB  quit
.fi
.SH "Application Resources"
.B xman
contains the following application-specific resources:
.IP "\fBbothShown\fR (Class \fBBoolean\fR)"
If
.BR true ,
both the directory and the manual page to appear at start up; if
.BR false ,
only one is shown.
The default is
.BR false .
.IP "\fBdirectoryFontNormal\fR (Class \fBFont\fR)"
The font to use for the directory text.
.IP "\fBdirectoryHeight\fR (Class \fBDirectoryHeight\fR)"
The height, in pixels, of the directory when the directory and the manual page
are shown simultaneously.
.IP "\fBhelpCursor\fR (Class \fBCursor\fR)"
The cursor to use in the help window.
.IP "\fBhelpFile\fR (Class \fBFile\fR)"
Use this rather than the system's default helpfile.
.IP "\fBmanpageCursor\fR (Class \fBCursor\fR)"
The cursor to use in the manual-page window.
.IP "\fBmanualFontBold\fR (Class \fBFont\fR)"
The font to use for bold text in the manual pages.
.IP "\fBmanualFontItalic\fR (Class \fBFont\fR)"
The font to use for italic text in the manual pages.
.IP "\fBmanualFontNormal\fR (Class \fBFont\fR)"
The font to use for normal text in the manual pages.
.IP "\fBpointerColor\fR (Class \fBForeground\fR)"
This is the color of all the cursors (pointers) specified above.
The name was chosen to be compatible with
.BR xterm .
.IP "\fBsearchEntryCursor\fR (Class \fBCursor\fR)"
The cursor to use in the search entry text widget.
.IP "\fBtopBox\fR (Class \fBBoolean\fR)"
If
.BR true ,
.B xman
first displays the control window.
If
.BR false ,
it displays a manual page at start-up.
The default is
.BR true .
.IP "\fBtopCursor\fR (Class \fBCursor\fR)"
The cursor to use in the top box.
.IP "\fBverticalList\fR (Class \fBBoolean\fR)"
If
.BR true ,
the directory listing is organized vertically.
The default is
.BR false ,
i.e., the directory is organized horizontally.
.SH "Global Actions"
.B xman
uses global actions to define how it interacts with the user.
This lets you modify the translation table of any widget
and binds an event to the new user action.
.B xman
recognizes the following global actions:
.IP \fBCreateNewManpage()\fR
This action may be used anywhere, and creates a new manual-page
display window.
.IP "\fBGotoPage(\fIpage\fB)\fR"
When used in a manual page display window this will allow the user to
move between a directory and manual page display.  The \fIpage\fR argument can
be either \fBDirectory\fR or \fBManualPage\fP."
.IP "\fBPopupHelp()\fR"
This action may be used anywhere, and will pop-up the help widget.
.IP "\fBPopupSearch()\fR"
This action may be used anywhere except in a help window.
It will cause the search pop-up to become active and visible on the screen,
allowing the user search for a manual page.
.IP "\fBQuit()\fR"
This action may be used anywhere, and will exit xman.
.IP \fBRemoveThisManpage()\fR
This action may be used in any manual page or help display window.
When called it will remove the window, and clean up all resources
associated with it.
.IP \fBSaveFormattedPage(\fIaction\fB)\fR
This action can only be used in the \fBlikeToSave\fR pop-up widget, and
tells
.B xman
whether to
.B Save
or
.B Cancel
a save of the  manual page that has just been formatted.
.IP "\fBSearch(\fItype\fB, \fIaction\fB)\fR"
Only useful when used in a pop-up search routine,
this action causes the search widget to perform the named-search type
on the string in the search pop-up's value widget.
This action will also pops down the search widget.
.I type
can be
.BR Apropos ,
.BR Manpage ,
or
.BR Cancel .
If an
.I action
of
.B Open
is specified, then
.B xman
opens a new manual page to display the results of the search, otherwise
.B xman
attempts to display the results in the parent of the search pop-up.
.IP \fBShowVersion()\fR
This action may be called from any manual page or help display window, and
causes the informational display line to show the current version of
.BR xman .
.SH Environment
.B xman
reads the following environmental variables:
.IP \fBDISPLAY\fR
The default host and display to use.
.IP \fBMANPATH\fR
The search path for manual pages.
Directories are separated by
colons; for example:
.DM
	/usr/man:/mit/kit/man:/foo/bar/man
.DE
.IP \fBXENVIRONMENT\fR
The name of a resource file that overrides the global resources
stored in the
.B RESOURCE_MANAGER
property.
.IP \fBXAPPLRESDIR\fR
A string that has the suffix
.BR Xman .
This string gives the full path name of a user's
resource file.
.B xman
merges this file into the resource data base after
.BR /usr/X11/lib/app-defaults/Xman ,
and before the resources that are attached to the display.
.SH Files
\fB/usr/lib/X11/app-defaults/Xman\fR \(em Specify required resources
.SH "See Also"
.B
X applications
.R
.br
\*(CO Lexicon:
.B
apropos,
man
.R
.SH Notes
Copyright \(co 1988 by the Massachusetts Institute of Technology.
.PP
.II "Peterson, Chris"
.II "Shein, Barry"
.B xman
was written by
Chris Peterson of the MIT X Consortium.
It is based on the X10 version written by Barry Shein,
formerly of Boston University.
