


XMAN(1)                                                               XMAN(1)



NAME
  xman - Manual page display program for the X Window System

SYNOPSIS
  xxmmaann [ -_o_p_t_i_o_n_s ... ]

DESCRIPTION
  _X_m_a_n is a manual page browser.  The default size of the initial _x_m_a_n window
  is small so that you can leave it running throughout your entire login ses-
  sion.  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.  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 _x_m_a_n.

  For further information on using _x_m_a_n, please read the on-line help infor-
  mation.  Most of this manual will discuss customization of _x_m_a_n.

OPTIONS

  Xman supports all standard Toolkit command line arguments (see _X(1)).  The
  following additional arguments are supported.


  --hheellppffiillee _f_i_l_e_n_a_m_e
       Specifies a helpfile to use other than the default.

  --bbootthhsshhoowwnn
       Allows both the manual page and manual directory to be on the screen
       at the same time.

  --nnoottooppbbooxx
       Starts without the Top Menu with the three buttons in it.

  --ggeeoommeettrryy _W_x_H+_X+_Y
       Sets the size and location of the Top Menu with the three buttons in
       it.

  --ppaaggeessiizzee _W_x_H+_X+_Y
       Sets the size and location of all the Manual Pages.

CUSTOMIZING XMAN

  _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
  environment 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 /mit/kit/man:/usr/man

  By default, _x_m_a_n will search each of the following directories (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

  For instance, a user has three directories in her manual path and each con-
  tain a directory called _m_a_n_3.  All these manual pages will appear alphabet-
  ically 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 MAN-
  PATH, or there are no manual pages in any of the directories called _m_a_n_o
  then no menu item will be displayed for the section called (_o) _O_l_d.

THE MANDESC FILE

  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 section by section basis, and individual manual pages may not be han-
  dled in this manner.  (Although generous use of symbolic links - see _l_n(1)
  - will allow almost any configuration you can imagine.)

  The format of the mandesc file is a character followed by a label.  The
  character 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:

  2Programmer Subroutines
  3Programmer Subroutines

  This will add a menu item to the _S_e_c_t_i_o_n_s menu that would bring up a list-
  ing 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.

  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 searching 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 one.

  no default sections
  1(1) User Commands
  2Programmer Subroutines
  3Programmer 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 <char-
  acter> 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.

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

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


APPLICATION RESOURCES
  _x_m_a_n has the following application-specific resources which allow customi-
  zations unique to _x_m_a_n.

  mmaannuuaallFFoonnttNNoorrmmaall (Class FFoonntt)
                    The font to use for normal text in the manual pages.

  mmaannuuaallFFoonnttBBoolldd (Class FFoonntt)
                    The font to use for bold text in the manual pages.

  mmaannuuaallFFoonnttIIttaalliicc (Class FFoonntt)
                    The font to use for italic text in the manual pages.

  ddiirreeccttoorryyFFoonnttNNoorrmmaall (Class FFoonntt)
                    The font to use for the directory text.

  bbootthhSShhoowwnn (Class BBoooolleeaann)
                    Either `true' or `false,' specifies whether or not you
                    want both the directory and the manual page shown at
                    start up.

  ddiirreeccttoorryyHHeeiigghhtt (Class DDiirreeccttoorryyHHeeiigghhtt)
                    The height in pixels of the directory, when the directory
                    and the manual page are shown simultaneously.

  ttooppCCuurrssoorr (Class CCuurrssoorr)
                    The cursor to use in the top box.

  hheellppCCuurrssoorr (Class CCuurrssoorr)
                    The cursor to use in the help window.

  mmaannppaaggeeCCuurrssoorr (Class CCuurrssoorr)
                    The cursor to use in the manual page window.

  sseeaarrcchhEEnnttrryyCCuurrssoorr (Class CCuurrssoorr)
                    The cursor to use in the search entry text widget.

  ppooiinntteerrCCoolloorr (Class FFoorreeggrroouunndd)
                    This is the color of all the cursors (pointers) specified
                    above.  The name was chosen to be compatible with xterm.

  hheellppFFiillee  (Class FFiillee)
                    Use this rather than the system default helpfile.

  ttooppBBooxx (Class BBoooolleeaann)
                    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.

  vveerrttiiccaallLLiisstt (Class BBoooolleeaann)
                    Either `true' or `false,' determines whether the direc-
                    tory listing is vertically or horizontally organized.
                    The default is horizontal (false).

GLOBAL ACTIONS
  _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:

  GGoottooPPaaggee((_p_a_g_e)) When 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 DDiirreeccttoorryy or MMaannuu--
                 aallPPaaggee.

  QQuuiitt(())         This action may be used anywhere, and will exit xman.

  SSeeaarrcchh((_t_y_p_e,, _a_c_t_i_o_n))
                 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 _t_y_p_e argument can
                 be either AApprrooppooss, MMaannppaaggee or CCaanncceell.  If an _a_c_t_i_o_n of OOppeenn
                 is 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.

  PPooppuuppHHeellpp(())    This action may be used anywhere, and will popup the help
                 widget.

  PPooppuuppSSeeaarrcchh(())  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.

  CCrreeaatteeNNeewwMMaannppaaggee(())
                 This action may be used anywhere, and will create a new
                 manual page display window.

  RReemmoovveeTThhiissMMaannppaaggee(())
                 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.

  SSaavveeFFoorrmmaatttteeddPPaaggee((_a_c_t_i_o_n))
                 This action can only be used in the lliikkeeTTooSSaavvee popup widget,
                 and tells xman whether to SSaavvee or CCaanncceell a save of the
                 manual page that has just been formatted.

  SShhoowwVVeerrssiioonn(())  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

  <_m_a_n_p_a_t_h _d_i_r_e_c_t_o_r_y>//mmaann<<_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>//ccaatt<<_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>//mmaannddeesscc

  //uussrr//lliibb//XX1111//aapppp--ddeeffaauullttss//XXmmaann
                           specifies required resources

  //ttmmpp                     _X_m_a_n creates temporary files in /tmp for all
                           unformatted man pages and all apropos searches.

SEE ALSO
  _X(1), _m_a_n(1), _a_p_r_o_p_o_s(1), _c_a_t_m_a_n(8), _A_t_h_e_n_a _W_i_d_g_e_t _S_e_t

ENVIRONMENT

  DDIISSPPLLAAYY        the default host and display to use.

  MMAANNPPAATTHH        the search path for manual pages.  Directories are separated
                 by colons (e.g. /usr/man:/mit/kit/man:/foo/bar/man).

  XXEENNVVIIRROONNMMEENNTT   to get the name of a resource file that overrides the global
                 resources stored in the RESOURCE_MANAGER property.

  XXAAPPPPLLRREESSDDIIRR    A 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 sys-
                 tem app-defaults file, and before the resources that are
                 attached to the display.

COPYRIGHT
  Copyright 1988 by Massachusetts Institute of Technology.
  See _X(_1) for a full statement of rights and permissions.

AUTHORS
  Chris Peterson, MIT X Consortium from the V10 version written by Barry
  Shein formerly of Boston University.


























