xman(1) — USER COMMANDS

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. Typing Control-S will pop up a window prompting for a specific manual page to display. You may display more than one manual page browser window at a time 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.

OPTIONS

−aproposfile path
specifies the pathname of a file to search for manual page descriptions instead of the default /usr/lib/X11/xman.apropos.

−noaproposlist
sets the aproposList resource to False.

−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.

DEFAULT BEHAVIOR ON UNIX SYSTEM V/88 Release 4

By default, xman searches the parent manpage directories /usr/share/man, /usr/share/x_man, /usr/share/motif_man, and /usr/share/ncd_man for a predefined set of subdirectories that contain manual pages.

The following default subdirectories and their corresponding man directories are searched:

SubdirectorySection Name
cat1(1) User Commands
cat2(2) System Calls
cat3(3) Subroutines
cat4(4) Devices
cat5(5) File Formats
cat6(6) Games
cat7(7) Miscellaneous
cat8(8) System Administration
catl(l) Local
catn(n) New
cato(o) Old
catp(p) Public

DEFAULT BEHAVIOR ON UNIX SYSTEM V/88 Release 32

By default, xman searches the parent manpage directory /usr/catman for a predefined set of subdirectories that contain manual pages.

The following default directories are searched:

Subdirectory        Section Name
u_man/man1       Commands and Application Programs (1)
u_man/man1c      UUCP Utilities (1c)
a_man/man1m      Maintenance Commands (1m)
a_man/man7       Special Files (7)
a_man/man8       System Maintenance Procedures (8)
p_man/man1       Miscellaneous Utilities (1)
p_man/man2       System Calls (2)
p_man/man2p      Signal Functions (2p)
p_man/man3       Functions and Libraries (3)
p_man/man3c      C Programming Language Utilities (3c)
p_man/man1m      Math Libraries (1m)
p_man/man3n      Internet/Networking Utilities (3n)
p_man/man3p      TERMIO Functions (3p)
p_man/man3s      I/O Functions (3s)
p_man/man3x      Specialized Libraries (3x)
p_man/man4       File Formats (4)
p_man/man5       Miscellaneous Features (5)
n_man/man1m      Network and NFS Administration (1m)
n_man/man1n      Network Commands (1n)
n_man/man2n      Network and NFS System Calls (2n)
n_man/man3n      Network Functions and Libraries (3n)
n_man/man3r      Network RPC and YP Functions (3r)
n_man/man4       Network File Formats (4)
x_man/man1       X Clients and Commands (1)
x_man/man1m      X Administration (1m)
x_man/man3       X Library Functions (3X)
x_man/man3X      X Library Functions (3X)
x_man/man3Xt     X Toolkit Functions (3Xt)
x_man/man3Xaw    X Athena Widgets (3Xaw)
motif_man/man1   Motif Clients (1)
motif_man/man3   Motif Toolkit Functions (3X)
motif_man/man3Xm 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 on UNIX SYSTEM V/88 Release 32:

MANPATH=/usr/catman:/usr/local/catman
export MANPATH

The following is a sample shell command for setting and exporting the variable on UNIX SYSTEM V/88 Release 4:

MANPATH=/usr/share/man:/usr/share/x_man:/usr/local/catman
export MANPATH

Note that the value of the MANPATH variable is used instead of, not in addition to, the default directories. This means that if you use the MANPATH variable and want /usr/share/man, /usr/share/x_man, and /usr/share/ncd_man to be searched, these paths must be explicitly listed in the MANPATH variable. In the example shown above, the default directory /usr/share/motif_man will not be searched.

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 “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/share/man and /usr/share/x_man. And suppose each parent directory contains a subdirectory called cat1. All the manual page filenames found in both cat1 subdirectories will appear in a single, alphabetically sorted list when the user clicks on the menu item called (1) User Commands.

xman deletes from its 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 cat7 in any of the parent directories in your MANPATH, or if there are no manual pages in any of the subdirectories called cat7, no menu item will be displayed for the section called (7) Miscellaneous.

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 Sections menu.

A user or system manager can control the content of the 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/share/x_man/mandesc is a correct pathname on UNIX SYSTEM V/88 Release 4. And /usr/catman/mandesc is a correct pathname on UNIX SYSTEM V/88 Release 32. 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.

There are two methods for storing paths in the mandesc file:

1) An entry 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 Sections menu. The following is an example of a valid line:

myman/cat3Xt:X Toolkit Manpages

2) An entry is a digit or letter followed by the label string without any separator. The digit or letter must match the section suffix for of the manpage subdirectory you wish to be searched. The subdirectory name must begin with either "cat" or "man". The following is an example of a valid line:

3X Toolkit Manpages

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

Suppose that /usr/share/x_man contains at least two subdirectories: cat1 and cat3. By default, the manpages in these two directories would be merged with the corresponding directories in /usr/share/man /usr/share/motif_man, and /usr/share/ncd_man. Instead, you would like to create separate menu items for the X Commands and the X Library and X Toolkit Functions. The /usr/share/x_man/mandesc file would look like this:

cat1:(1) X Commands
cat3:(3X) X Library and Toolkit Functions

The effect of this file is to create two new menu items in the Sections menu, which will bring up a listing of all manual pages in the named subdirectories.

X command manpages in /usr/share/x_man/cat1 will be listed separately from the user command manpages in /usr/share/man/cat1. The X library and toolkit function manpages, which reside in the same directory, will be accessible through two separate menu items. 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 all default directories or those defined in your MANPATH. xman silently ignores the fact that subdirectories are not found.

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.

WIDGETS

In order to specify resources, it is useful to know the hierarchy of the widgets which compose xman. In the notation below, indentation indicates hierarchical structure. The widget class name is given first, followed by the widget instance name.

Xman xman(This widget is never used)
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
TopLevelShell listpopup
Paned pane
Box box
Command Done
Label label
Viewport viewport
List list

APPLICATION RESOURCES

xman has the following application-specific resources which allow customizations unique to xman.

aproposFile (Class File)
The pathname of a file to search for manual page descriptions instead of the default /usr/lib/X11/xman.apropos.

aproposList (Class Boolean)
If True, the file specified by the aproposFile resource is searched and the results are displayed in a separate window containing a list widget that allows you to select a manpage by clicking on its name or description. If False, suppresses search of the file referred to by the aproposFile resource and causes the system’s apropos command to be executed instead. The results are placed in a manual page window. The default value is True.

manualFontNormal (Class Font)
The font to use for normal text in the manual pages.

manualFontBold (Class Font)
The font to use for bold text in the manual pages.

manualFontItalic (Class Font)
The font to use for italic text in the manual pages.

directoryFontNormal (Class Font)
The font to use for the directory text.

bothShown (Class Boolean)
Either True or False, specifies whether or not you want both the directory and the manual page shown at start up.

directoryHeight (Class DirectoryHeight)
The height in pixels of the directory, when the directory and the manual page are shown simultaneously.

topCursor (Class Cursor)
The cursor to use in the top box.

helpCursor (Class Cursor)
The cursor to use in the help window.

manpageCursor (Class Cursor)
The cursor to use in the manual page window.

searchEntryCursor (Class Cursor)
The cursor to use in the search entry text widget.

pointerColor (Class Foreground)
This is the color of all the cursors (pointers) specified above. The name was chosen to be compatible with xterm.

helpFile (Class File)
Use this rather than the system default helpfile.

topBox (Class Boolean)
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 start-up. The default is true.

verticalList (Class Boolean)
Either True or False, determines whether the directory listing is vertically or horizontally organized. The default is horizontal (false).

GLOBAL ACTIONS

Xman defines all user interaction through global actions. This allows the user to modify the translation table of any widget, and bind any event to the new user action. The list of actions supported by xman are:

GotoPage (page) When used in a manual page display window this will allow the user to move between a directory and manual page display. The page argument can be either Directory or ManualPage.

Quit() This action may be used anywhere and will exit xman.

Search(type, action)
Only useful when used in a search popup, this action will cause the search widget to perform the named search type on the string in the search popup’s value widget. This action will also pop down the search widget. The type argument can be either Apropos, Manpage or Cancel. If an action of Open is specified, and the type is Manpage, then xman will open a new manual page to display the results of the search, otherwise xman will attempt to display the manpage text in the parent of the search popup. If the type is Apropos and the aproposList resource is True (the default), the file specified by the aproposFile resource is searched and the results displayed in a separate window that allows you to click on a manual page name or description to bring up the desired manual page. If the type is Apropos and the aproposList resource is False, the system’s apropos command is executed. If an action of Open is specified, the results are displayed in a new manual page window, otherwise xman will attempt to display the results in the parent of the search popup.

PopupHelp() This action may be used anywhere, and will popup the help widget.

PopupSearch() This action may be used anywhere except in a help window. It will cause the search popup to become active and visible on the screen, allowing the user search for a manual page.

CreateNewManpage()
This action may be used anywhere, and will create a new manual page display window.

RemoveThisManpage()
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.

ShowVersion() This action may be called from any manual page or help display window, and will cause the informational display line to show the current version of xman.

FILES

On UNIX SYSTEM V/88 Release 4:
/usr/share/man:/usr/share/x_man:/usr/share/motif_man:
/usr/share/ncd_man (or directories specified in MANPATH)
On UNIX SYSTEM V/88 Release 32:
/usr/catman (or directories specified in MANPATH)
<manpath directory>/mandesc
/usr/lib/X11/app−defaults/Xmanspecifies required resources
/usr/lib/X11/xman.aproposdefault apropos description file
/tmpxman creates temporary files in /tmp
for all unformatted man pages and all
apropos searches.

ENVIRONMENT

DISPLAY The default host and display to use.

MANPATH The search path for manual pages. Directories are separated by colons, as illustrated below.

/usr/share/man:/usr/local/catman

XENVIRONMENT
To get the name of a resource file that overrides the global resources stored in the RESOURCE_MANAGER property.

XAPPLRESDIR A string that will have xman appended to it. This string will be the full pathname of a user app−defaults file to be merged into the resource database after the system app−defaults file, and before the resources that are attached to the display.

— X Utilities

Museum

Related Articles