home *** CD-ROM | disk | FTP | other *** search
/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / altsrcs / 1 / 1734 / README < prev    next >
Encoding:
Text File  |  1990-12-28  |  6.3 KB  |  146 lines
  1.         README for XMON - Graphically monitor a list
  2.  
  3.          George Ferguson, ferguson@cs.rochester.edu
  4.  
  5.                   7 Aug 1990
  6.  
  7. DISCLAIMER:
  8.  
  9.      This is an ALPHA release. While it has been in use for some time
  10.      at our site, there are certainly many bugs left to find.
  11.  
  12.      This software is provided as is with no warranty expressed or implied.
  13.      I hope you find it useful, but I won't be held responsable for
  14.      any damage that may occur from reading, compiling, installing or
  15.      using it.
  16.  
  17.      You are free to use any part of this code for other purposes. It
  18.      would be nice if you could keep my name on some part of whatever the
  19.      final product is.
  20.  
  21.      Note: This program is similar in functionality to the Faceserver
  22.      program posted to the net previously. (Actually I don't know that
  23.      since I never saw it run, only read the documentation.) Xmon is
  24.      a much less ambitious program whose purpose was to (a) provide some
  25.      useful tools, and (b) produce code that could by used to simplify
  26.      future X projects. No infringement on the Faceserver code is
  27.      intended, and I hope none is perceived.
  28.  
  29. OVERVIEW:
  30.  
  31.      Xmon is a program which monitors a list and displays its contents
  32.      graphically in an X window. The list is usually generated by a
  33.      command and the updates performed at regular intervals. Xmon is
  34.      built using the Athena widgets. The icons to be displayed are
  35.      standard X bitmap files (32x32 size normally) which can be created
  36.      with the "bitmap" program as documented in the man page.
  37.  
  38.      Xmon by itself is not very interesting, but using xmon as a core we
  39.      have built more useful tools including: xru (monitor users), xrf
  40.      (monitor machines), xls (directory browser), and xfrom (monitor
  41.      mailbox). These specializations are performed using Athena widget
  42.      resources.
  43.  
  44.      This distribution includes code that can easily be used for other
  45.      X applications. In particular, translate.c implements a mapping
  46.      between class names and Widget classes which, together with the function
  47.      initWidgets() in xmon.c, implements dynamic creation of all the widgets
  48.      in an application for complete "customizability".
  49.  
  50.      Many utility programs are included in this distribution, including
  51.      ad2c (convert app-defaults files to C declarations), ru-awk and rf-awk
  52.      (filters for rwho and ruptime), and some other stuff in the util
  53.      directory.
  54.  
  55. PRINCIPLES OF OPERATION:
  56.  
  57.      This is my feeble attempt to explain how the code works so that those
  58.      who want to customize it at either the C code or resource levels can
  59.      do so.
  60.  
  61.      The basic principle is that xmon (or whatever derived program in class
  62.      Xmon) runs the command specified by the updateCommand resource at a
  63.      rate given by the updateInterval resource. The output is gathered and
  64.      if the nameCommand resourec is non-NULL it is piped through that command.
  65.      The first word of each line of the result used as the name of an icon
  66.      to look for in the directory given by the faceDirectory resource. If
  67.      it is not found then a default icon is used. The icons are displayed
  68.      in a Box widget (by default, and I don't see why you'd change it).
  69.  
  70.      In order to speed things up, xmon caches both Widgets and Bitmaps,
  71.      the former to prevent extra calls to XtCreateManagedWidget() and the
  72.      latter to avoid extra XReadBitmapFromFile() calls. There is a
  73.      translation action (xmon-reinit()) which clears the cache.
  74.  
  75.      The anticipated most common usage is to click on a "face". By default
  76.      this puts the entire line of text from the updateCommand into the
  77.      infoLabel widget. Xmon allows you complete control over what widgets you
  78.      want. In particular, you can create buttons which use information from
  79.      the currently selected "face" to create a command to execute. This is
  80.      provided by the xmon-cmd() translation action which is fully documented
  81.      in the man page. Some other actions are also provided, see the man page.
  82.  
  83. INSTALLATION:
  84.  
  85.      1. Edit the Imakefile to reflect any changes for your site. These
  86.     include setting BINDIR, LIBDIR, and MANDIR if needed, and
  87.     checking CDEBUGFLAGS if debugging or optimization is desired.
  88.  
  89.     The variable FACEDIR should be where the face icons will live
  90.     and should be the same as the entry for Xmon.faceDirectory in
  91.     Xmon.ad. The directory will be created if necessary.
  92.  
  93.     The variable XMONDIR should be where any utility programs will
  94.     live, and will also be created if necessary.
  95.  
  96.     If you want to use any of the utility programs like ru-awk, rf-awk,
  97.     name2icon or xls-cmd, make sure that the definition of UTIL includes
  98.     the ones you want so they will be installed correctly.
  99.  
  100.     If you've installed "ad2c" you may want to change the declaration
  101.     of AD2C.
  102.  
  103.     See the comment concerning the derived tools under (4) below.
  104.  
  105.      2. Edit Xmon.ad as well, checking especially the entries for
  106.         Xmon.faceDirectory
  107.         *.updateCommand
  108.         *.nameCommand
  109.     You may also want to change other defaults; consult the man page for
  110.     details. Note that the application-defaults file contains the defaults
  111.     for the entire Xmon _class_ of programs, which includes xru, xrf, xls
  112.     and xfrom, so be sure to check the whole file for necessary changes.
  113.  
  114.     If you use the utility program "xls-cmd" (in the util directory),
  115.     edit it so that the xmon executable is properly found. You may not
  116.     need a full path if xmon lives in a standard directory. The utility
  117.     program "name2icon" is used in the xls.nameCommand resource; it
  118.     should be edited to reflect your installation (use XMONDIR).
  119.  
  120.     The FILES section of the man page xmon.man should be edited to reflect
  121.     the locations of the various files.
  122.  
  123.      2. Execute
  124.         % xmkmf
  125.     to create the Makefile.
  126.  
  127.      3. Execute
  128.         % make depend
  129.     to add the dependencies to the Makefile. This is necessary to
  130.     ensure that Xmon.ad.h is created when needed.
  131.     IMPORTANT: Ignore the error message from makedepend when Xmon.ad.h
  132.            is not found; it will be created automatically.
  133.  
  134.      4. Make the package using
  135.         % make
  136.     or install it directly with
  137.         % make install install.man
  138.     The default installation will create symbolic links for xru, xrf,
  139.     xls and xfrom in BINDIR. Alternatively you can achieve this effect by
  140.     invoking xmon with the "-name" option, either from an alias or a
  141.     shell script, as described in the man page. You can install shell
  142.     scripts automatically by editing the Imakefile; see the comments
  143.     above the "install::" target.
  144.  
  145.  
  146.