XMAN(1) XMAN(1)
NAME
xman - manual page display program for the X Window
System
SYNOPSIS
xman [-options ...]
DESCRIPTION
xman is a manual page browser. The default size of the
initial xman window is small so that you can leave it
running throughout your entire login session. In the
initial window there are three options: Help pops up a
window with online help, Quit exits, and Manual Page
pops up a window with a manual page browser. More than
one manual page browser window can be popped up from a
single execution of xman.
For further information on using xman menu options and
scrolling in the text window, read the online help
information.
DEFAULT BEHAVIOR
By default, xman searches the parent manpage directory
/usr/catman for a predefined set of subdirectories that
contain manual pages.
The following default subdirectories are searched on
SYSTEM V/68:
Subdirectory Section Name
user User Commands and X Clients (1)
admin Maintenance Commands (1M)
prog/p1 Programmer Commands (p1)
prog/p2 System Calls (2)
prog/p3 Functions and Libraries (3)
prog/p3c C Programming Language Utilities (3C)
prog/p3m Math Libraries (3M)
prog/p3n Internet Utilities (3N)
prog/p3s I/O Functions (3S)
prog/p3x Specialized Libraries (3x)
prog/p3X X Library Functions (3X)
prog/p3Xt X Toolkit Functions (3Xt)
prog/p3Xmf Motif Toolkit Functions (3Xm)
prog/p4 File Formats (4)
prog/p5 Miscellaneous Features (5)
packages/man1m Network and NFS Administration (1M)
packages/man1n Network Commands (1N)
packages/man2nfNetwork and NFS System Calls (2N)
packages/man3n Network Functions and Libraries (3N)
packages/man3r Network RPC and YP Functions (3R)
packages/man4 Network File Formats (4)
packages/man7n TCP/IP and Device Drivers (7N)
- 1 -
XMAN(1) XMAN(1)
The following default directories are searched on
SYSTEM V/88:
Subdirectory Section Name
uman/man1 Commands and Application Programs (1)
uman/man1c UUCP Utilities (1C)
aman/man1m Maintenance Commands (1M)
aman/man7 Special Files (7)
aman/man8 System Maintenance Procedures (8)
pman/man1 Miscellaneous Utilities (1)
pman/man2 System Calls (2)
pman/man2p Signal Functions (2P)
pman/man3 Functions and Libraries (3)
pman/man3c C Programming Language Utilities (3C)
pman/man1m Math Libraries (1m)
pman/man3n Internet/Networking Utilities (3N)
pman/man3p TERMIO Functions (3P)
pman/man3s I/O Functions (3S)
pman/man3x Specialized Libraries (3x)
pman/man4 File Formats (4)
pman/man5 Miscellaneous Features (5)
nman/man1m Network and NFS Administration (1M)
nman/man1n Network Commands (1N)
nman/man2n Network and NFS System Calls (2N)
nman/man3n Network Functions and Libraries (3N)
nman/man3r Network RPC and YP Functions (3R)
nman/man4 Network File Formats (4)
xman/man1 X Clients and Commands (1)
xman/man1m X Administration (1M)
xman/man3X X Library Functions (3X)
xman/man3Xt X Toolkit Functions (3Xt)
motifman/man1 Motif Clients (1)
motifman/man3 Motif Toolkit Functions (3Xm)
CUSTOMIZING XMAN
xman allows you to add to, delete from, or modify the
default search directories using a MANPATH environment
variable and a manpage description file.
MANPATH VARIABLE
If the MANPATH environment variable is set, xman uses
it to determine which parent directories to search for
subdirectories containing manpages. This environment
variable is expected to be a colon-separated list of
pathnames.
The following is a sample shell command for setting and
exporting the variable:
MANPATH=/usr/catman:/usr/local/catman
export MANPATH
- 2 -
XMAN(1) XMAN(1)
Note that the value of the MANPATH variable is used
instead of, not in addition to, the default /usr/catman
directory. This means that if you use the MANPATH
variable and want /usr/catman to be searched,
/usr/catman must be explicitly listed in the MANPATH
variable.
xman searches for all the built-in subdirectories in
each parent directory listed in the MANPATH variable.
(It is possible to override this behavior as described
in the MANDESC File section.) If manual pages exist in
a given subdirectory, they are added to the list of
manual pages for the corresponding menu item. A menu
item is only displayed for those sections that actually
contain manual pages. xman silently ignores the fact
that a default subdirectory is missing from a given
parent directory.
xman collates and sorts manpage filenames according to
category. For example, suppose you have two parent
directories in your manual path: /usr/catman and
/usr/local/catman. Each parent directory contains a
subdirectory called user. All the manual page
filenames found in both user subdirectories will appear
in a single, alphabetically sorted list when the user
clicks on the menu item called User Commands (1).
xman deletes from its Manual Sections menu any
subdirectories that are not found in at least one
MANPATH parent directory or any subdirectories that
contain no manpages. If, for example, there is no
subdirectory called prog/p5 in any of the parent
directories in your MANPATH, or if there are no manual
pages in any of the subdirectories called prog/p5, no
menu item will be displayed for the section called
Miscellaneous Features (5).
THE MANDESC FILE
xman allows you to specify which subdirectories to
search, whether to search the built-in default
subdirectories, and the name that each searched
subdirectory will map to in the Manual Sections menu.
A user or system manager can control the content of the
Manual Sections menu by creating a file called mandesc.
The mandesc file must reside at the top of each MANPATH
parent directory where it is to take effect. For
example, /usr/catman/mandesc or
/usr/local/catman/mandesc are correct pathnames. It is
possible to override or add to the default subdirectory
searches using a mandesc file in one parent directory,
while allowing the default searches in another.
- 3 -
XMAN(1) XMAN(1)
The format of the mandesc file is a pair of colon-
separated strings. The first string is the name of a
subdirectory in one of the MANPATH parent-directory
components where manpages are located. The second
string is the descriptive label that is associated with
manpages in this directory in the Manual Sections menu.
A single space character should be used to separate
words in the label so that the label can be matched
easily when merging manpages from multiple
subdirectories under a one menu item.
Example 1
Suppose that /usr/local/catman contains three
subdirectories: user, prog/p3X, and prog/p3Xt. You
would also like to create separate menu items for the X
Library Function manpages and for the X Toolkit
Functions. You would also like the X client program
manpage names to be merged with other user manpages.
The mandesc file would look like this:
user:User Commands (1)
prog/p3X:X Library Functions (3X)
prog/p3Xt:X Toolkit Functions (3Xt)
The effect of this file is to add the two new menu
items to the Manual Sections menu, which will bring up
a listing of all manual pages in the named
subdirectories.
Because the label name for user manpages is exactly the
same as the default name (including white space), the X
client manpages will be merged with the default user
manpages, as if the manpage files resided in the same
directory. Words in the menu labels for the built-in
default subdirectories are separated by exactly one
space character. Note, however, that the remaining
default subdirectory names are still searched for in
/usr/local/catman. xman silently ignores the fact that
subdirectories are not found.
Example 2
To prevent xman searches for nonexistent default
subdirectories in a given parent directory, add the
following line anywhere in the mandesc file.
no default sections
This keeps xman from searching the default
subdirectories in that parent directory only.
For example, suppose you want all the programmer
subroutines in /usr/catman to appear in a single,
sorted list. You also want to change the default User
- 4 -
XMAN(1) XMAN(1)
Commands (1) label to indicate that manpages for X
clients are also contained in the user subdirectory.
You must create a /usr/catman/mandesc file. In it, you
must duplicate the default subdirectory names (see the
Default Behavior section) that you do not want to
modify. Then, change the label associated with
subdirectories you do want listed differently:
no default sections
user:X Clients and User Commands (1)
prog/p1:Programmer Commands (1)
prog/p2:System Calls (2)
prog/p3c:Programmer Subroutines
prog/p3m:Programmer Subroutines
prog/p3n:Programmer Subroutines
prog/p3s:Programmer Subroutines
prog/p3x:Programmer Subroutines
prog/p4:File Formats (4)
prog/p5:Miscellaneous Features (5)
admin:Administrator Commands (1M)
These entries cause xman to list only the menu items
specified in the mandesc file for the /usr/catman
directory. Only one menu item appears for Programmer
Subroutines, which brings up a combined list of all
manpages in the five subroutine directories.
COMMAND LINE OPTIONS
-helpfile filename
specifies a helpfile to use other than the default.
-bothshown
allows both the manual page and manual directory to
be on the screen at the same time.
-notopbox
starts without the top menu with the three buttons
in it.
-geometry WxH+X+Y
sets the size and location of the top menu with the
three buttons in it.
-pagesize WxH+X+Y
sets the size and location of all the manual pages.
-bw pixels or -borderwidth pixels
specifies the width of the border for all windows
in xman.
-bd color or -bordercolor color
specifies the color of the borders of all windows
- 5 -
XMAN(1) XMAN(1)
in xman.
-fg color or -foreground color
specifies the foreground color to be used.
-bg color or -background color
specifies the background color to be used.
-fn font or -font font
specifies the font to use for all buttons and
labels.
-display host:display[.screen]
specifies a display other than the default
specified by the DISPLAY environment variable.
-name name
specifies the name to use when retrieving
resources.
-title title
specifies the title of this application.
-xrm resources
allows a resource to be specified on the command
line.
XMAN RESOURCES
xman is the class name for resources of the xman
client.
The xman program uses the following X resources:
foreground, background, width, height, borderWidth, and
borderColor.
In order to change the default values for widget
resources, you need to know widget names. The
following are the names of some of the most common
widgets. You can also reference widgets by class. The
most common classes are Label, Command, and Text.
topBox
The top menu.
help
The help window.
manualBrowser
The manual page display window.
xmanCommands
Manual page command popup menu.
- 6 -
XMAN(1) XMAN(1)
xmanSections
Manual page section popup menu.
xmanSearch
Manual page search popup menu.
In addition, xman has application-specific resources
that allow unique xman customizations:
manualFontNormal
The font to use for normal text in the manual
pages.
manualFontBold
The font to use for bold text in the manual pages.
manualFontItalic
The font to use for italic text in the manual
pages.
directoryFontNormal
The font to use for the directory text.
bothShown
Either true or false. Specifies whether or not you
want both the directory and the manual page shown
at start-up.
directoryHeight
The height in pixels of the directory when the
directory and the manual page are shown
simultaneously.
topCursor
The cursor to use in the top box.
helpCursor
The cursor to use in the help window.
manpageCursor
The cursor to use in the manual page window.
searchEntryCursor
The cursor to use in the search entry text widget.
helpFile
Use this rather than the system default helpfile.
topBox
Either true or false. Determines whether the top
box (containing the help, quit and manual page
buttons) or a manual page is put on the screen at
- 7 -
XMAN(1) XMAN(1)
start-up. The default is true.
verticalList
Either true or false. Determines whether the
directory listing is vertically or horizontally
organized. The default is horizontal (false).
Here are a few examples of how to string all this
information together into a resource specification that
can be used on the command line with the -xrm flag or
added to your .Xresource or .Xdefaults file:
xman*Command.foreground: Blue
All command buttons are blue.
xman*topBox*foreground: Blue
Everything in the top menu has a blue foreground.
xman*Text.border: Red
All text widgets have a red border.
xman*Label.font: 9x15
All label buttons have a 9x15 font.
The instance name xman can be replaced with the class
name XMan.
FILES
/usr/catman (or directories specified in MANPATH)
mandesc
SEE ALSO
man(1)
ENVIRONMENT
DISPLAY
The default host and display to use.
MANPATH
The search path for manual pages. Directories are
separated by colons (e.g.,
/usr/catman:/usr/local/catman).
BUGS
The -fn and -font options only specify the fonts for
the command button and not the text of the manpages or
directories.
AUTHORS
Chris Peterson, MIT Project Athena from the V10 version
written by Barry Shein of Boston University
- 8 -