[0m


XMAN(1)             UNIX Programmer's Manual		  XMAN(1)



[1mNAME
     [0mxman - Manual page display program for the X Window System.

[1mSYNOPSIS
     xman [0m[-options ...]

[1mDESCRIPTION
     [0m_X_m_a_n is a manual page browser.  The default size of the ini-
     tial _x_m_a_n window is small so that you can leave it running
     throughout your entire login session.  In the initial window
     there are three options: _H_e_l_p will pop up a window with on-
     line help, _Q_u_i_t will exit, and _M_a_n_u_a_l _P_a_g_e will pop up a
     window with a manual page browser in it.  You may pop up
     more than one manual page browser window from a single exe-
     cution of _x_m_a_n.

     For further information on using _x_m_a_n please read the on-
     line help information.  The rest of this manual page will
     discuss customization of _x_m_a_n.

[1mCUSTOMIZING XMAN
     [0m_X_m_a_n allows customization of both the directories to be
     searched for manual pages, and the name that each directory
     will map to in the _S_e_c_t_i_o_n_s menu.	Xman determines which
     directories it will search by reading the _M_A_N_P_A_T_H environ-
     ment variable.  If no _M_A_N_P_A_T_H is found then the directory is
     /usr/man is searched on POSIX systems.  This environment is
     expected to be a colon-separated list of directories for
     xman to search.

     setenv MANPATH /usr/users/steve/man:/usr/share/man

     By default, _x_m_a_n will search each of the following direc-
     tories (in each of the directories specified in the users
     MANPATH) for manual pages.  If manual pages exist in that
     directory then they are added to list of manual pages for
     the corresponding menu item.  A menu item is only displayed
     for those sections that actually contain manual pages.

     Directory	    Section Name
     ---------	    ------------
     man1	    (1) User Commands
     man2	    (2) System Calls
     man3	    (3) Subroutines
     man4	    (4) Devices
     man5	    (5) File Formats
     man6	    (6) Games
     man7	    (7) Miscellaneous
     man8	    (8) Sys. Administration
     manl	    (l) Local
     mann	    (n) New
     mano	    (o) Old



Printed 9/2/93		    Release 4				1






XMAN(1)             UNIX Programmer's Manual		  XMAN(1)



     For instance, a user has three directories in her manual
     path and each contain a directory called _m_a_n_3.  All these
     manual pages will appear alphabetically sorted when the user
     selects the menu item called (_3) _S_u_b_r_o_u_t_i_n_e_s.  If there is
     no directory called _m_a_n_o in any of the directories in her
     MANPATH, or there are no manual pages in any of the direc-
     tories called _m_a_n_o then no menu item will be displayed for
     the section called (_o) _O_l_d.

     By using the _m_a_n_d_e_s_c file a user or system manager is able
     to more closely control which manual pages will appear in
     each of the sections represented by menu items in the _S_e_c_-
     _t_i_o_n_s menu.  This functionality is only available on a sec-
     tion by section basis, and individual manual pages may not
     be handled in this manner (Although generous use of symbolic
     links - ln(1) - will allow almost any configuration you can
     imagine).

     The format of the mandesc file is two strings per line:
     first a section name, and then a label.  The section name
     determines which of the sections will be added under this
     label.  For instance suppose that you would like to create
     an extra menu item that contains all programmer subroutines.
     This label should contain all manual pages in both sections
     two and three.  The _m_a_n_d_e_s_c file would look like this:

     2 Programmer Subroutines
     3 Programmer Subroutines

     This will add a menu item to the _S_e_c_t_i_o_n_s menu that would
     bring up a listing of all manual pages in sections two and
     three of the Programmers Manual.  Since the label names are
     _e_x_a_c_t_l_y the same they will be added to the same section.
     Note, however, that the original sections still exist.

     To create a menu item containing only Motif subroutines, the
     entry would be:

     3Xm Motif Subroutines


     If you want to completely ignore the default sections in a
     manual directory then add the line:

     no default sections

     anywhere in your mandesc file.  This keeps xman from search-
     ing the default manual sections _i_n _t_h_a_t _d_i_r_e_c_t_o_r_y _o_n_l_y.  As
     an example, suppose you want to do the same thing as above,
     but you don't think that it is useful to have the _S_y_s_t_e_m
     _C_a_l_l_s or _S_u_b_r_o_u_t_i_n_e_s sections any longer.	You would need to
     duplicate the default entries, as well as adding your new



Printed 9/2/93		    Release 4				2






XMAN(1)             UNIX Programmer's Manual		  XMAN(1)



     one.

     no default sections
     1 (1) User Commands
     2 Programmer Subroutines
     3 Programmer Subroutines
     4 (4) Devices
     5 (5) File Formats
     6 (6) Games
     7 (7) Miscellaneous
     8 (8) Sys. Administration
     l (l) Local
     n (n) New
     o (o) Old

     Xman will read any section that is of the from
     _m_a_n<_c_h_a_r_a_c_t_e_r>, where <character> is an upper or lower case
     letter (they are treated distinctly) or a numeral (0-9).  Be
     warned, however, that man(1) and catman(8) will not search
     directories that are non-standard.

[1mCOMMAND LINE OPTIONS
     [0mXman supports all standard Toolkit command line arguments
     (see _X(_1)).  The following additional arguments are sup-
     ported.


     [1m-helpfile [0m_f_i_l_e_n_a_m_e
	  Specifies a helpfile to use other than the default.

     [1m-bothshown
	  [0mAllows both the manual page and manual directory to be
	  on the screen at the same time.

     [1m-notopbox
	  [0mStarts without the Top Menu with the three buttons in
	  it.

     [1m-geometry [0m_W_x_H+_X+_Y
	  Sets the size and location of the Top Menu with the
	  three buttons in it.

     [1m-pagesize [0m_W_x_H+_X+_Y
	  Sets the size and location of all the Manual Pages.

[1mWIDGETS
     [0mIn order to specify resources, it is useful to know the
     hierarchy of the widgets which compose _x_m_a_n.  In the nota-
     tion below, indentation indicates hierarchical structure.
     The widget class name is given first, followed by the widget
     instance name.




Printed 9/2/93		    Release 4				3






XMAN(1)             UNIX Programmer's Manual		  XMAN(1)



     Xman xman (_T_h_i_s _w_i_d_g_e_t _i_s _n_e_v_e_r _u_s_e_d)
	  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



Printed 9/2/93		    Release 4				4






XMAN(1)             UNIX Programmer's Manual		  XMAN(1)



	       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


[1mAPPLICATION RESOURCES
     [0m_x_m_a_n has the following application-specific resources which
     allow customizations unique to _x_m_a_n.

     [1mmanualFontNormal [0m(Class [1mFont[0m)
		       The font to use for normal text in the
		       manual pages.

     [1mmanualFontBold [0m(Class [1mFont[0m)
		       The font to use for bold text in the
		       manual pages.

     [1mmanualFontItalic [0m(Class [1mFont[0m)
		       The font to use for italic text in the
		       manual pages.

     [1mdirectoryFontNormal [0m(Class [1mFont[0m)
		       The font to use for the directory text.

     [1mbothShown [0m(Class [1mBoolean[0m)
		       Either 'true' or 'false', specifies
		       whether or not you want both the directory
		       and the manual page shown at start up.

     [1mdirectoryHeight [0m(Class [1mDirectoryHeight[0m)



Printed 9/2/93		    Release 4				5






XMAN(1)             UNIX Programmer's Manual		  XMAN(1)



		       The height in pixels of the directory,
		       when the directory and the manual page are
		       shown simultaneously.

     [1mtopCursor [0m(Class [1mCursor[0m)
		       The cursor to use in the top box.

     [1mhelpCursor [0m(Class [1mCursor[0m)
		       The cursor to use in the help window.

     [1mmanpageCursor [0m(Class [1mCursor[0m)
		       The cursor to use in the manual page win-
		       dow.

     [1msearchEntryCursor [0m(Class [1mCursor[0m)
		       The cursor to use in the search entry text
		       widget.

     [1mpointerColor [0m(Class [1mForeground[0m)
		       This is the color of all the cursors
		       (pointers) specified above.  The name was
		       chosen to be compatible with xterm.

     [1mhelpFile  [0m(Class [1mFile[0m)
		       Use this rather than the system default
		       helpfile.

     [1mtopBox [0m(Class [1mBoolean[0m)
		       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.

     [1mverticalList [0m(Class [1mBoolean[0m)
		       Either 'true' or 'false', determines
		       whether the directory listing is verti-
		       cally or horizontally organized.  The
		       default is horizontal (false).

     [1msaveCatFiles [0m(Class [1mSaveCatFiles[0m)
		       Controls whether formatted manual pages
		       should be saved in the appropriate 'cat'
		       directory.  Saving the formatted pages
		       makes future lookup much faster, at the
		       expense of a potentially large amount of
		       disk space.  If this resource is 'Yes',
		       then _x_m_a_n always attempts to save the for-
		       matted page.  If it is 'No', then the for-
		       matted page is not saved.  If the resource
		       is set to 'Ask', then _x_m_a_n pops up a dia-
		       log box inviting the user to choose



Printed 9/2/93		    Release 4				6






XMAN(1)             UNIX Programmer's Manual		  XMAN(1)



		       whether or not to save the page.  The
		       default is 'Yes'.

     [1mtitleBarFormat [0m(Class [1mTitleBarFormat[0m)
		       A string describing the contents of the
		       window manager's title bar.  This string
		       may contain the sequence [1m%s[0m, which will be
		       replaced by the name of the manual page
		       being displayed.  The default value is
		       "Xman - %s".  This string is ignored for
		       the Help window.

     [1miconNameFormat [0m(Class [1mIconNameFormat[0m)
		       As titleBarFormat, but describes the win-
		       dow manager's icon label (if used).  The
		       default value is "Man Page".  A %s may be
		       included as with titleBarFormat.  This
		       string is ignored for the Help window.

[1mGLOBAL ACTIONS
     [0m_X_m_a_n 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 _x_m_a_n are:

     [1mGotoPage([0m_p_a_g_e[1m) [0mWhen used in a manual page display window
		    this will allow the user to move between a
		    directory and manual page display.	The _p_a_g_e
		    argument can be either [1mDirectory [0mor [1mManual-
		    Page[0m.

     [1mQuit()	    [0mThis action may be used anywhere, and will
		    exit xman.

     [1mSearch([0m_t_y_p_e[1m, [0m_a_c_t_i_o_n[1m)
		    [0mOnly useful when used in a search popup, this
		    action will cause the search widget to per-
		    form the named search type on the string in
		    the search popup's value widget. This action
		    will also pop down the search widget. The
		    _t_y_p_e argument can be either [1mApropos[0m, [1mManpage
		    [0mor [1mCancel[0m.	If an _a_c_t_i_o_n of [1mOpen [0mis specified
		    then xman will open a new manual page to
		    display the results of the search, otherwise
		    xman will attempt to display the results in
		    the parent of the search popup.

     [1mFollowReference([0m_t_y_p_e[1m)
		    [0mOnly useful when bound to a mouse button in
		    the manualPage widget.  This triggers
		    automatic cross-reference following, as
		    described in the on-line help page.  The



Printed 9/2/93		    Release 4				7






XMAN(1)             UNIX Programmer's Manual		  XMAN(1)



		    parameter should be _S_a_m_e_W_i_n_d_o_w to display the
		    new manual page in the current window, or
		    _N_e_w_W_i_n_d_o_w to pop it up in a new window.

     [1mPopupHelp()    [0mThis action may be used anywhere, and will
		    popup the help widget.

     [1mPopupSearch()  [0mThis 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.

     [1mCreateNewManpage()
		    [0mThis action may be used anywhere, and will
		    create a new manual page display window.

     [1mRemoveThisManpage()
		    [0mThis 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.

     [1mSaveFormattedPage([0m_a_c_t_i_o_n[1m)
		    [0mThis action can only be used in the "likeTo-
		    Save" popup widget, and tells xman whether to
		    [1mSave [0mor [1mCancel [0ma save of the manual page that
		    has just been formatted.

     [1mShowVersion()  [0mThis 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.

[1mFILES
     [0m<_m_a_n_p_a_t_h _d_i_r_e_c_t_o_r_y>/man<_c_h_a_r_a_c_t_e_r>

     <_m_a_n_p_a_t_h _d_i_r_e_c_t_o_r_y>/cat<_c_h_a_r_a_c_t_e_r>

     <_m_a_n_p_a_t_h _d_i_r_e_c_t_o_r_y>/mandesc

     /usr/lib/X11/app-defaults/Xman
			      specifies required resources

     /tmp		      _X_m_a_n creates temporary files in
			      /tmp for all unformatted man pages
			      and all apropos searches.

[1mSEE ALSO
     [0mX(1), X(8C), man(1), apropos(1), catman(8), Athena Widget
     Set





Printed 9/2/93		    Release 4				8






XMAN(1)             UNIX Programmer's Manual		  XMAN(1)



[1mENVIRONMENT
     DISPLAY	    [0mthe default host and display to use.

     [1mMANPATH	    [0mthe search path for manual pages.  Direc-
		    tories are separated by colons (e.g.
		    /usr/share/man:/usr/users/steve/man).

     [1mXENVIRONMENT   [0mto get the name of a resource file that over-
		    rides the global resources stored in the
		    RESOURCE_MANAGER property.

     [1mXAPPLRESDIR    [0mA string that will have "Xman" appended to
		    it.  This string will be the full path name
		    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.

[1mBUGS
     [0mThere probably are some.

[1mCOPYRIGHT
     [0mCopyright 1988 by Massachusetts Institute of Technology.
     See _X(_1) for a full statement of rights and permissions.

[1mAUTHORS
     [0mChris Peterson, MIT X Consortium: from the V10 version writ-
     ten by Barry Shein formerly of Boston University.

     Steve Hunt, Acorn Computers Ltd: improved the formatting
     algorithm, sped up text display, and added automatic cross-
     reference following.























Printed 9/2/93		    Release 4				9



[0m