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 _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. 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 information. 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.

--hheellppffiillee _f_i_l_e_n_a_m_e Specifies a helpfile to use other than the default.
--bbootthhsshhoowwnn Allows both the manual page and manual directory to be on the screen at
the same time.
--nnoottooppbbooxx Starts without the Top Menu with the three buttons in it.
--ggeeoommeettrryy _W_x_H_+_X_+_Y Sets the size and location of the Top Menu with the three buttons in it.
--ppaaggeessiizzee _W_x_H_+_X_+_Y Sets the size and location of all the Manual Pages.

CUSTOMIZING XMAN

Xman 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, xman 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 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 directories called _m_a_n_o then no menu item will be displayed for the section called _(_o_) _O_l_d.

BSD AND LINUX SYSTEMS

In newer BSD and Linux systems, _X_m_a_n will search for a file named _/_e_t_c_/_m_a_n_._c_o_n_f which will contain the list of directories containing manual pages. See _m_a_n_._c_o_n_f(5) for a complete description of the file format.

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

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 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  
                    .
                    . (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 customizations unique to _x_m_a_n.

mmaannuuaallFFoonnttNNoorrmmaall (Class FFoonntt)
The font to use for normal text in the manual pages.
mmaannuuaallFFoonnttBBoolldd (Class FFoonntt)
The font to use for bold text in the manual pages.
mmaannuuaallFFoonnttIIttaalliicc (Class FFoonntt)
The font to use for italic text in the manual pages.
ddiirreeccttoorryyFFoonnttNNoorrmmaall (Class FFoonntt)
The font to use for the directory text.
bbootthhSShhoowwnn (Class BBoooolleeaann)
Either `true' or `false,' specifies whether or not you want both the directory and the manual page shown at start up.
ddiirreeccttoorryyHHeeiigghhtt (Class DDiirreeccttoorryyHHeeiigghhtt)
The height in pixels of the directory, when the directory and the manual page are shown simultaneously.
ttooppCCuurrssoorr (Class CCuurrssoorr)
The cursor to use in the top box.
hheellppCCuurrssoorr (Class CCuurrssoorr)
The cursor to use in the help window.
mmaannppaaggeeCCuurrssoorr (Class CCuurrssoorr)
The cursor to use in the manual page window.
sseeaarrcchhEEnnttrryyCCuurrssoorr (Class CCuurrssoorr)
The cursor to use in the search entry text widget.
ppooiinntteerrCCoolloorr (Class FFoorreeggrroouunndd)
This is the color of all the cursors (pointers) specified above. The name was chosen to be compatible with xterm.
hheellppFFiillee (Class FFiillee)
Use this rather than the system default helpfile.
ttooppBBooxx (Class BBoooolleeaann)
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.
vveerrttiiccaallLLiisstt (Class BBoooolleeaann)
Either `true' or `false,' determines whether the directory 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:
GotoPage(_p_a_g_e))<> <> WWhheenn uusseedd iinn aa mmaannuuaall ppaaggee ddiissppllaayy wwiinnddooww tthhiiss wwiillll aallllooww tthhee uusseerr ttoo mmoovvee bbeettwweeeenn aa ddiirreeccttoorryy aanndd mmaannuuaall ppaaggee ddiissppllaayy.. TThhee _p_a_g_e aarrgguummeenntt ccaann bbee eeiitthheerr DDiirreeccttoorryy oorr MMaannuuaallPPaaggee.. <> <>QQuuiitt(())<> <> TThhiiss aaccttiioonn mmaayy bbee uusseedd aannyywwhheerree,, aanndd wwiillll eexxiitt xxmmaann.. <> <>SSeeaarrcchh((_t_y_p_e,, _a_c_t_i_o_n))<> <> OOnnllyy uusseeffuull wwhheenn uusseedd iinn aa sseeaarrcchh ppooppuupp,, tthhiiss aaccttiioonn wwiillll ccaauussee tthhee sseeaarrcchh wwiiddggeett ttoo ppeerrffoorrmm tthhee nnaammeedd sseeaarrcchh ttyyppee oonn tthhee ssttrriinngg iinn tthhee sseeaarrcchh ppooppuupp''ss vvaalluuee wwiiddggeett.. TThhiiss aaccttiioonn wwiillll aallssoo ppoopp ddoowwnn tthhee sseeaarrcchh wwiiddggeett.. TThhee _t_y_p_e aarrgguummeenntt ccaann bbee eeiitthheerr AApprrooppooss,, MMaannppaaggee oorr CCaanncceell.. IIff aann _a_c_t_i_o_n ooff OOppeenn iiss ssppeecciiffiieedd tthheenn xxmmaann wwiillll ooppeenn aa nneeww mmaannuuaall ppaaggee ttoo ddiissppllaayy tthhee rreessuullttss ooff tthhee sseeaarrcchh,, ootthheerrwwiissee xxmmaann wwiillll aatttteemmpptt ttoo ddiissppllaayy tthhee rreessuullttss iinn tthhee ppaarreenntt ooff tthhee sseeaarrcchh ppooppuupp.. <> <>PPooppuuppHHeellpp(())<> <> TThhiiss aaccttiioonn mmaayy bbee uusseedd aannyywwhheerree,, aanndd wwiillll ppooppuupp tthhee hheellpp wwiiddggeett.. <> <>PPooppuuppSSeeaarrcchh(())<> <> TThhiiss aaccttiioonn mmaayy bbee uusseedd aannyywwhheerree eexxcceepptt iinn aa hheellpp wwiinnddooww.. IItt wwiillll ccaauussee tthhee sseeaarrcchh ppooppuupp ttoo bbeeccoommee aaccttiivvee aanndd vviissiibbllee oonn tthhee ssccrreeeenn,, aalllloowwiinngg tthhee uusseerr sseeaarrcchh ffoorr aa mmaannuuaall ppaaggee.. <> <>CCrreeaatteeNNeewwMMaannppaaggee(())<> <> TThhiiss aaccttiioonn mmaayy bbee uusseedd aannyywwhheerree,, aanndd wwiillll ccrreeaattee aa nneeww mmaannuuaall ppaaggee ddiissppllaayy wwiinnddooww.. <> <>RReemmoovveeTThhiissMMaannppaaggee(())<> <> TThhiiss aaccttiioonn mmaayy bbee uusseedd iinn aannyy mmaannuuaall ppaaggee oorr hheellpp ddiissppllaayy wwiinnddooww.. WWhheenn ccaalllleedd iitt wwiillll rreemmoovvee tthhee wwiinnddooww,, aanndd cclleeaann uupp aallll rreessoouurrcceess aassssoocciiaatteedd wwiitthh iitt.. <> <>SSaavveeFFoorrmmaatttteeddPPaaggee((_a_c_t_i_o_n))<> <> TThhiiss aaccttiioonn ccaann oonnllyy bbee uusseedd iinn tthhee lliikkeeTTooSSaavvee ppooppuupp wwiiddggeett,, aanndd tteellllss xxmmaann wwhheetthheerr ttoo SSaavvee oorr CCaanncceell aa ssaavvee ooff tthhee mmaannuuaall ppaaggee tthhaatt hhaass jjuusstt bbeeeenn ffoorrmmaatttteedd.. <> <>SShhoowwVVeerrssiioonn(())<> <> TThhiiss aaccttiioonn mmaayy bbee ccaalllleedd ffrroomm aannyy mmaannuuaall ppaaggee oorr hheellpp ddiissppllaayy wwiinnddooww,, aanndd wwiillll ccaauussee tthhee iinnffoorrmmaattiioonnaall ddiissppllaayy lliinnee ttoo sshhooww tthhee ccuurrrreenntt vveerrssiioonn ooff xxmmaann.. <> <> FFIILLEESS <> <> <> <>_<_m_a_n_p_a_t_h _d_i_r_e_c_t_o_r_y_>//mmaann<<_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_>//ccaatt<<_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_>//mmaannddeesscc<> <> <> <>//uussrr//XX1111RR77//lliibb//XX1111//aapppp--ddeeffaauullttss//XXmmaann<> ssppeecciiffiieess rreeqquuiirreedd rreessoouurrcceess.. <> <> <>//ttmmpp<> <>XXmmaann<> <> ccrreeaatteess tteemmppoorraarryy ffiilleess iinn //ttmmpp ffoorr aallll uunnffoorrmmaatttteedd mmaann ppaaggeess aanndd aallll aapprrooppooss sseeaarrcchheess.. <> <> SSEEEE AALLSSOO <> <>XX((77))<> <>mmaann((11))<> <>aapprrooppooss((11))<> <>ccaattmmaann((88))<> <>AAtthheennaa WWiiddggeett SSeett<> <> EENNVVIIRROONNMMEENNTT <> <> <> <>DDIISSPPLLAAYY<> <> tthhee ddeeffaauulltt hhoosstt aanndd ddiissppllaayy ttoo uussee.. <> <>MMAANNPPAATTHH<> <> tthhee sseeaarrcchh ppaatthh ffoorr mmaannuuaall ppaaggeess.. DDiirreeccttoorriieess aarree sseeppaarraatteedd bbyy ccoolloonnss ((ee..gg.. //uussrr//mmaann:://mmiitt//kkiitt//mmaann:://ffoooo//bbaarr//mmaann)).. <> <>XXEENNVVIIRROONNMMEENNTT<> <> ttoo ggeett tthhee nnaammee ooff aa rreessoouurrccee ffiillee tthhaatt oovveerrrriiddeess tthhee gglloobbaall rreessoouurrcceess ssttoorreedd iinn tthhee RREESSOOUURRCCEE__MMAANNAAGGEERR pprrooppeerrttyy.. <> <>XXAAPPPPLLRREESSDDIIRR<> <> AA ssttrriinngg tthhaatt wwiillll hhaavvee ````XXmmaann'''' aappppeennddeedd ttoo iitt.. TThhiiss ssttrriinngg wwiillll bbee tthhee ffuullll ppaatthh nnaammee ooff aa uusseerr aapppp--ddeeffaauullttss ffiillee ttoo bbee mmeerrggeedd iinnttoo tthhee rreessoouurrccee ddaattaabbaassee aafftteerr tthhee ssyysstteemm aapppp--ddeeffaauullttss ffiillee,, aanndd bbeeffoorree tthhee rreessoouurrcceess tthhaatt aarree aattttaacchheedd ttoo tthhee ddiissppllaayy.. <> SSeeee _X_(_7_) ffoorr aa ffuullll ssttaatteemmeenntt ooff rriigghhttss aanndd ppeerrmmiissssiioonnss.. <> <> AAUUTTHHOORRSS <> CChhrriiss PPeetteerrssoonn,, MMIITT XX CCoonnssoorrttiiuumm ffrroomm tthhee VV1100 vveerrssiioonn wwrriitttteenn bbyy BBaarrrryy SShheeiinn ffoorrmmeerrllyy ooff BBoossttoonn UUnniivveerrssiittyy.. BBuugg ffiixxeess aanndd LLiinnuuxx ssuuppppoorrtt bbyy CCaarrllooss AA MM ddooss SSaannttooss,, ffoorr TThhee XXFFrreeee8866 PPrroojjeecctt.. <>